MULTICS TECHNICAL BULLETIN MT8-253 


To? Distripution 
From? J. Berson 
Datei 02/03/76 


Subject? Release 2 of the Multics Sort/Merge 


Attacned is information about Release 2 of the Multics 
sort/Merges which Is scheduled for Multics Retease 4.0 In June 
1976. There are four write-ups, including sort commands, merge 
command, sort_ subroutines merge_ subroutine, In the usual form 
for tne Multics Programmers*® Manual, and one write-up of 
additional interfaces to be documented in the PLM. 


Comments and criticlsms are solicited, whether on technical 
aspects or on the documentation. They may be sent to Joel Berson 
at Honeywell Billerica by mali' or phones; or vis “mal! Berson 
MSORT™ on either the MIT or Phoenlx Multics systems. 
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Multics Project internal working documentation. Not to be 
reproduced or distributed outsiae the Multics Project. 
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NEW FUNCTIONS 
A Merge, or fille coltatilon, function has been added. 


A subroutine interface for both the Sort and Merge has been 
added. 


Support for the SORT portion of the ANSI COBOL Sort/Merge 
Module, Level 2, has been added. (The COBOL MERGE function 
is not supported by this package). 


Additional data types for keys and multlpte key fletds are 
supported. Release 1 supported oniy character string and a 
single key field. 


Addltional storage media and file organizations are 
supported for the input and otuput files. Essentlally any 
fille can be supported which can be read or written 
sequentially via iox. using any availabie I/0 module. 
Release 41 supported only sequential input and output files 
in the Multics storage system (using vflie_). 


Tne following additional user exit points are provided: 


Input _record exit? Permits the user to alter, delete, or 
. insert records before they enter the 
sorting or merging process: 


output_record exit: Permits the user to atter, delete, 
Inserts, or summarlze records comlng 
out of the sorting or merging process 
before they are aritten to the output 
file. 


Sequence checking for output records nas been added. 
A flle size argument has been added. 


Command arguments for measurement and testing have been 
added (-tIlme, -merge_order, ana -string_size). 
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CHANGED SPECIFICATIONS 


The keyword -sort_desc {(-sd) must precede the pathname of 
the Sort Description (when the Sort Description is supoiled 
in a segment). In Release i, the pathname of the Sort 
Oescription must be the first argument and Is not preceded 
by a keyword. 


QUESTIONS ABOUT DOCUMENTATION 


I would like to raise the following questions about 
documentation of tne Sort/Merge. 


Shoutd the Sort and the Merge be documented in four separate 
MPM write-ups, as attached; or should the Merge (command and 
subroutine) be documented in two shorter write-ups which 
then refer to the two Sort write-ups for detaiis? There is 
much in common between the Sort and the Merge. On fhe other 
hands, noting differences appiicadie to the Merge In the Sort 
write-ups may be somewhat complicated and confusing. 


Should there be a separate Users’ Guide for the Sort/Merge? 
If sos what information should go in the MPM and what in fhe 
Users* Guide? Some Information not presentiy in the MPM 
write-ups which might go Into a Users® Gulde is! 


text of error messages 


description of the report produced by the Sort/Merge 
{various counts of records processed$ data produced by 
the -time argument) 


I/0 usage3$ eege for PL/I I/0, Fortran, record_stream_, 
SYN_»s eTfCe 


Relationship between flte size, work space required, 
optimizations atc. 


Should the additional command arguments described in the PLM 
write-up be documented directiy in the MPM Commands 
write-ups? 


sort sort 


Namet sort 


The sort command provides a generatized file sorting 
capabllitys which Is specialized for executlon by user 
supplied parameters. The basic functlon of the Sort Is to 
read one or more input files of records which are not 
ordered, sort those records according to the values of one 
or more Key fleids. and write a single fille of ordered (or 
“ranked™) records. The Sort nas the following general 
capabilities: 


Input and output files may be on any storage medium and in 
any file organization$ 


Very targe files, such as muitisegment filles, can be sorted; 


Multipie key fields and most PL/I string and numeric data 
types may be specified; 


Exits to user supptied subroutines are permitted at several 
points during tne sorting process. 


In addition to arguments to the sort commands other 
information is necessary to speciailze the Sort for a particular 
execution. This information, called the Sort Description, can be 
supplied elther through the user"s terminat or in a segment. 


The description glven here of the sort command Is sufficlent 
for situations where the Sort Is free standing; that Iss where 
no user supplied orocedures are executed. (User supplied 
procedures are called “exlt procedures”.) Additional Information 
is necessary for executing the sort command with exit procedures, 
and Is contained in the description of the sort _ subroutine In 
the Multics Programmers’ Manual, Subroutines, Sectlon II. 


' 
INPUT AND OUTPUT 


The user can specify the Input and output files. In this 
environment, the Sort reads the input files and writes the output 
flle. Each Input or output file may be stored on any medium and 
in any file organization supported by an I/0 module through lox_. 
The I/0 module may be one of the Multics system I/0 modules (such 
as tape_ansi_), or one suppiled by a specific Installation, or 
one written by a uSer. An Input or output file is specified 
eltner by a pathname or by an attach description. 


Alternativetys the user can supply either. an input file 


procedure or an oufput_fite procedure (or both). An invnut_file 
procedure Is responsible for reading input and releasing records 
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to tne Sort. An output_file procedure is responsible for 
retrieving records (ranked by the Sort) from the Sort and writing 
ouftpute 


In ali cases, records may be elther fixed length or variable 
tengthe 


KEY FIELDS 


The user can specify the key flelds to be used In ranking 
records. Key fietds are described in the Keys statement of the 
Sort Description. Up to 20 key fields may be specified. Any 
PL/I string or numeric dafa type = except compiex or pictured - 
may be specified for a given key field. Ranking may be 
ascending, descendingy or mixed. For a cnaracter string fietd, 
the collating sequence Is that of tne Multics standard character 
set. 


Aiternatively, the user can specify a user supplied compare 
procedure, which is then used to rank records. 


The orlginal order of records with equal keys IS preserved 
(FIFO order). Original input order Is defined as follows? 


14% If two equal records come from different input files, then 
the record from the file which is specified eariler in the 
command fine is first. 


26 If two equal records come from the same inout flle, then the 
record which is earfier in the file is first. 


EXITS 


The Sort provides exIits fo user suppiled procedures at 
specific points during the sorting process. Exit orocedures are 
named in the Exits statement of the Sort Descriotion. Tne 
following exit points are provided? 


inout_file To obtain input records and release them one 
by one fo the sorting process. 


output_file To retrieve ranked records one by one from 
the sorting process and oufpuft fhem. 


input_record To perform special processing for each Inpuf 


record, such as deleting, insertings or 
aitering records to be input to the Sorte 
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output_record 


compare 


To perform special processing for each output 
record, such as deleting, inserting, or 
altering records to be output from the Sort; 
or summarizing data by accumulating it Into a 
Summary record. 


To compare two records; tnat iss to rank them 
for the sorting process. 
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sort -input_specs output _spec control _args 


where?’ 


Le 


input_specs 


-Input_file pathname 


-if patnname 


indicates that the user 1s specifying the 
input files. Up to 16 Input files may be 
specified. Each Inout file specification 
{each input_spec) may be supplied in one of 
the followlng forms? 


If an input ffite is in the Multics 
Storage system and its file organization 
is either sequentlai or indexed, then if 
may be specified by its pathname. The 
flie may be either a single segment or a 
muitisegment fille. The star convention 
can not be used. 


An Input flie specified by a pathname 
will be attached using the attach 
description “vfite_ pathname”. 


-input_description “attach _desc” 
-ids “attach_desc” If an inout fille is not in the Multics 


storage system or its fiie organization 
Is nelther sequential nor Indexed, then 
it must be specified by an attach 
description. Tne attach descr iotion 
must be quoted. The target I/0 module 
specifled via the attach descriotion 
must suppor ¢ the sequential_inout 
opening mode and the iox. entry ocint 
read record. 


Pathnames and attach descriptions can be 
intermixed in the inputf_specs argument. 


If tne user Is supplying an iJInput_flle exit 
procedure, then the inpuf_specs argument must 
be omitted and the Iinouet_file exit procedure 
must be named in the Exits statement of fhe 
Sort Description. 
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output spec indicates tnat tne user is specifying the 
output file. Only one output fille can be 
specifled. The output file specification 
{output _spec) may be supplied In one of fhe 
following forms? 


-output_file pathname 

-of pathname If the output file is In the Multics 
storage system and its flile organization 
is sequential, then It may be specifled 
by Its pathname. The file may be either 
a slngle segment or a multisegment fille. 


The equais convention may be used. 1 
it is. it is appiied to the pathname of 
the first Input file and the first Input 
fille must be specifled by a pathname, 
not by an attach description. 


An output flie specified by a pathname 
will be attached using the attach 
descrlotion “vfilie_ pathname”. Thus If 
the flle does not exist, it willl be 
created. If It does exists it will be 
overwritten. 


-output_flle -reptlace 

-of erp The output flie is to replace the first 
inout§ file. That input file will be 
overwritten during the merge phase of 
the Sorte If ereptace is used, the 
first input file must be specltfled by a 
pathname, not by an attach description. 


-output_description “attach_desc”™ 

-ods “attach_desc™ Lf the output file is not In the Multics 
storage system or its flle organlzatlion 
lis not sequentlat, then It must be 
specified by an attach description. The 
attach description must be quoted. The 
target I/0 modufe specifled via the 
attach description must support the 
sequentlal_outoput opening mode and the 
lox, entry point arite_recorde 


If the user is suppfyling an output_flie exit 
procedure, fhen the output_spec argument must 
pe omilttec and the outfout_file exlt procedure 
must be named in the Exits statement of the 
Sort Description. 
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control_args mus f 


-console_input 
“cl 


-sorf_desc sd_path 
-Sd sd_path 


sort 


be chosen from the following? 


Indicates that the Sort Description is 
read via the 1/0 switch user_Irput 
{which normality is the user’s terminal). 


indicates that the user Is svoecifying 
the pathname of tne segment contairing 
the Sort Description. 


€ither the -console_input or the -sort_aesc 
argument - but not both - must be specified. 
see the heading Sort Description beion. 


-temp_dir td_path 
-td td_path 


-filte_size f 


indicates that the user Is specifying 


‘the pathname of tne directory which wlll 


contain the Sort*s work files. The 
equals convention can not be used. 


If this argument is omitteds work filles 
wili pve contained in the user's process 
directory. 


This argument should be used when the 
process directory will not oboe Jlarge 
enough to contain the work files. The 
{wd] active function may be used for 
td_patn to place work fites in the 
user®s current working directory. 


specifies that the totai amount of data 
to be sorted Is f milftions of bytes. 
The argument f£ must be a decimal number. 
If the -file_size argument is omitted, 
the default assumption is aporoximately 
one milllon bytes (ff = i-G). 


This argument is Intended for use when 
some or all of the input flles are not 
in the storage system (that is, are not 
specified by patnhnames) or when an 
input _flte exit procedure Is used. In 
these cases the Sort cannot determine 
the amount of Inout data. (The Sort 
does compute tne total amount of input 
data which is in the storage system, 
using segment bit countse) The 
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-filte_size argument may afso be used 
when afl of the input flies are in the 
storage system dOut records are to be 
inserted or deleted through an 
input _record exit procedure. 


The e-flte size argument is used for 
optimization of performances the actual 
amount of input data can be consliderably 
farger without preventing the Sort from 
completing. The maximum amount of data 
which can be sorted is (Cin bytes) 
approximately 69 miftiilon times the 
square root of f- 


NOTES 


Arguments can appear In any order, out a pathname or attach 
description must immediatety follow Its keyword. 


The temporary directory pathname (td_path) is the name of a 
directory. The Sort Description pathname (sd path) is the name 
of a segment. 


Any pathname may be relative (to the user’s current working 
directory) or absolute. 
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aort Descrintion 


The Sort Description contains additional! Information to 
speclalize the Sort for a particular executlone The Information 
supplied may ode’ 


Keys - Description of one or more key flelds used for 
ranking records. 


Exits - Specification of which exit points are to be used 
and the names of the corresponding user supptled 
exit procedures. 


A Sort Description Is required. As a minimum, the user must 
specify how records are to be ranked, either by describing key 
fietds in tne Keys statement or by naming a compare exit 
procedure in the Exits statement. Other information In the Sort 
Description is opptionai. 


The Sort Description may be supplied as a segment or read 
via the I/0 switch user_Input (normaity tne user*s terminal). 


If the Sort Description is supplied In a segment, Its 
pathname is specifled in the -sort_desc argument. 


If the Sort Description is read via the user's terminal, 
the -console_input argument is used. The Sort orints “Input?"™ 
via the 1/0 switch user_output and waits for inpute Tne user 
then types the Sort Oescription. To terminate the Sort 
Description, the user types a tine consisting of a period (".") 
followed by a line feed. {This fine is not part of the Sort 
Description.) . 


SYNTAX OF THE SORT DESCRIPTION 


A Sort ODescrlotion consists of a set of statements. Each 
statement must begin witn a function keyword. The function 
keyword is followed by the function keyword delimiter colon 
("3"). The statement Itself consists of one or more parameters, 
separated by voarameter delimiters. The parameter delimlters are 
spaceS, commas (","), or (in certain specific cases as specified 
- below) parentheses {(*(" and “)"%). Each statement must end with 
the statement delimiter semicoton ("3"). 


In the descriptions below, certain notational conventions 
are usede A word enclosed between the less than and greater than 
symbols ("<" and “>“) Ils a notational! variable, which must be 
replaced by an actual word or phrase of the Sort ODescription 
fanguagee A word not enclosed between < and > Is an actual word 
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of the Sort Oescription !anguage. A phrase enclosed between 
brackets ("f" and ™1%) is optlonal. A phrase enclosed between 
braces ("“{" and “}") and followed by an ellipsis ("eee") is 
required, and may be repeated one or more times. 


KEYS STATEMENT 


The Keys statement specifies key fields used to rank the 
records of the input files. The format of the Keys statement Is 


keys: ({<key_description>} eee } 

The Keys statement consists of a series of one or more 
<key_descriotion>s. The key descriptions are specified in order, 
the first describing the major key and the tast describing the 
most minor Keye Up to 29 key descriptions may be supplied. 


A key description is the specification of a single key 
field. The format of a <key_descriptilonm is? 


<datatype> (<size>) <position> [descending] 


where’ 

is <datatype> Is the data type of the key fleid. Tnis 
element is required. See the table below for 
the encoding of <datatype>. 

Ze <size> is the slze of tne key fleld, expressed in a 


form which depends on the data typee This 
element Ils requlred. 


For string data fypes, <size> is the tlength 
{characters or bits) of the field. The 
fength is the exact amount of space occupied 
oy the fleld.e 


For arithmetic data types, size is _ the 
precision (binary or decimal digits) of the 
fleid. Scale factor, lf anys must not be 
aritten (it is not required by the Sort). 
The space occupled is determined by _ the 
orecision in combinatlon wlth the data type 
and fhe alignment. (Atignment is soecified 
via <posltion>.) For an atigned binary fietd 
(flxed or floating). the space occupled is 
Increased if necessary to an Integral number 
of wordse 


Page i2 


3° 


be 


<position> 


<w> 


<yw> (<p>j 


aescending 
dsc 


<size> must be a decimal integer. The unlt 
Jepends on the data type. See the table 
dDelow for the semantics of <slze>. (The 


rules used are the same as those used by 
Muittics PL/I.) 


is the offset of the beginning of the key 
fleld, relative to the beginning of the 
recorde Consider fhe record as being aligned 
on a word boundary, as wiil be the case for a 
Multics PL/I structure. This element Is 
required, There are two formats: 


where <w> is the aord offset. Words are 
numbered from 0. for the first wora of 
the record. This format specifies to 
the Sort that the key fleld is aligned 
on aword or (if <w> is even) on a 
double wora boundary. 


where <w> Is the word portlon of the 
offset and <b> is the bit portion of the 
offset; that Is, the bolt offset wlthin 
the word. Bits are numbered from 9 to 
35 This format implies tnat the key 
fietd is not atlgned on a word boundary. 
If the key fletd Is aligned on ae word 
boundary but the user specifies a bit 
offset of 9 anyway, the Sort will 
operate correctiy although speed of 
execution may be affected. 


The formats for <positlon> and the values for 
<w> and <b> are consistent with those shown 
in Multics PL/I listings or used by debug. 


specifies descending order for ranking using 
this key field. This element may be omitted; 
the default is ascending order for thls key 
field. 
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DATATYPE ENGODING AND SEMANTICS OF SIZE 


Encoding ! Semantics of <sIize> 


of H (where <size> = n) | 
<datatype>i Unit Range Space Occupled 
Character string char 9 bit 41° 4095 on characters 
(Multics ASCII) character 
Bit string bit 1 bit 4° 4095 on oblts 
Fixed binary doin 1 bit 14-71 Aillgned? 


1 <n ¢ 35% one word 
36 «< n K& 71% two word 
Unaltigned! n+#iz olts 


Floating binary float bin ibit 1- 63 Aligned? 
1 £n € 278 one word 
36 <n < 63% two word 


Unallgned: n+9 obits 


Fixed decimal dec 9 bit i1- 59 n+ i digits 
(teaaing sign) digit 
Floating: decima! float dec 9 bit 1- 59 n + 2 digits 
digit 


In addition to the forms shown for <datatype> in the table 
above, the following varlents are also peraltted3 


The following alternate spellings may be used’ 
chartcnaracter bintbinary decidecimal 

The word “fixed™ may be used (or omltted). For example: 
fixed binibin fixed decidec 

The words may be written in any sequence. For example? 


float binibin float 
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EXAMPLES OF KEY DESCRIPTIONS 


char(10), 06418) 


Character strings Multics ASCII code, length 
ten characters; starts at bit 18 of word 0. 


char(8)s 4. descending 


character(&), 2s dsc 


bit(16), 92) 


bint17), 2 


bint17), 2448) 


bIinti)s 210) 


binli)s 2 


bDin(36)%s 2 


dec(6), 9(9) 


fioat dec(9), 6(9) 


Character string, Multics ASCII code, fengtn 
eight characters} starts at bIt 0g of word 13 
ranking is descending. 


Character strings Multics ASCII code, ftength 
four characters; starts at bit 9 of word 23 
ranking is descending. 


Bit string, lencth 16 bits; starts at bit 2 
of word 0. 


Fixed binary, precision 173 since no bit 
offset is speclifled, is atigned ana thus 
occupies one word (equivalent fo “bin(35), 
2"). 


Fixed binary», precision 173 since a obit 
offset is specified, is unallgned and 
occupies 18 bits$ starts at bit 18 of word 2 
(ieee, is in the low order half of word 2). 


Fixed binary, precision 13 unaligned and thus 
occuples 2 bits$ starts at bit 0 of word 2. 


Fixed binary, precision 13 allgned and. thus 
occuples one word (equivalent to “bint35), 
2") s 


Fixed binary, preclsion 363 since no bIt 
offset is specifled and precision is greater 
than 35 and word offset is even, is aligned 
and occupies two words (lequivatent fo 
“bint(71)-. 2”). 


Fixed decimal, 9 oit digit, oprecislon 63 
starts at bit 939 of word G and occuples 7 
digits including slgn {that Is, through the 


end of word 1). 


Floating decimal, 9 bit digits orecision 93 
starts at bit 9 of word 90 and occuples i1 
digits including exponent and sign (that IS, 
through tne end of word 2). 
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EXITS STATEMENT 


An Exits statement specifies fhe exlt procedures to be used 
during execution of the Sorte The format of an Exits statement 
is: 

exits: C<exit_descriptlon>} see 3} 

The Exits statement consists of a set of one or more 
<exit_descriptilon>s. Exit descriptions may be specifled In any 
ordere 

An exit description is the specification of one exit point 
and the user supplied exit procedure to be calted at that exit 
point. The format of an <exit_description> is? 


<exlf name> <user_name> 


where? 

1. <exit name> is the keyword naming the exit point at which 
the user suppliled exit procedure Is to be 
called. Exit names may be chosen from the 
following jist? 

iInput_filile 
output_file 
Input record 
output _record 
compare 
22 user_name is the name of the entry polnt of the user 


suppiled procedure. This parameter has the 
same syntax and semantics as a command name. 
That is 


User_name can be elther a segment name (eegee 
segment) or a segment name and an entry point 
name (@egey segment$entry_polnt). In these 
cases,» the user’s current search rules are 
appiled to find tne procedure. {If some 
segment is already known by the = specified 
reference name, that segment is used.) 


User _name can also be a pathname; that Is>, 
can specify a directory hlerarchy tocation, 
either relative (to the user®’s current 
working dlrectory) or absolute. In this 
case, fhe search ruies are not appiied and 
the pathname Is used to find the procedure. 


Page 16 


sort sort 


(If some other segment is already known by 
the specified reference name, that segment Is 
terminated first.) 


WRITING EXIT PROCEDURES 


The exit points to be used during an execution of the Sort 
and the names of the corresponding user supplied exif procedures 
are specified in the Exits statement as described above. The 
specifications for writing exit procedures (PL/I declare and call 
statements) and the functional requirements imposed upon exit 
procedures are given in the description of the sort_ subroutine 
in Section II of MPM Subroutinese 
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Examoles 


sort -linput_file sortein -output_file =.eout -console_input 
Input. . 
keys char(ig)s, G3 


In this example, the arguments of the command stete that 
there is one input flies, whose pathname Is sort.ln3 the output 
file pathname Is sorteout; the Sort Oescription is Inout via the 
user*s terminals; and by defauit the work files are contained in 
the user’s process dlrectorye 


The Sort ODescrlption states that there is one Keys a 
character string of tength 10 characters, starting at word 0 bit 
0 of the recorde There are no exits specif led. 


sort -temp_dir >udd>pooi -sortf_desce sd 


In this example the arguments of the command state that the 
work files are contained in the directory >udd>pool$ and the 
Sort Description is contained In the segment named sd. 


Assume that the segment sd contalns? 


keys fixed bin(35) O, char(8) 13 
exits: input_flte user$input, 
output_file user$output; 


Tne Sort Description states that there are two keys. Tne 
major key is an aligned fixed binary fletd of precislon 35, 
contained in word g§ of the records The minor key Is a character 
string of tength 8, contained in words i and 2 of the record. 


There are two exlts: an Input_flie procedure exlt and an 
output_file procedura exite The input_file exit procedure entry 
point is named user$input$ the output_flle exit procedure entry 
point 1s named userg$outpuf. These exits must be specifled 
because the command did not specify eitner an input file or an 
output fllie. 


sort elif sort_in cof srepiace -td {wd] esd sort_desc 


In this example the arguments of the command state that the 
Input file is named sort lin; the output fille ls to replace the 
Input files; work files are contained In the user*s current 
working directory; and the Sort Description Ils contained in the 
segment sort_desc. 
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sort -input_description “tape_ansi_ volt_1 -name a™ -if b \ 
-outpuf_description “vflle_c -extend”™ -cil 


In this exampie there are two input files. The first Input 
file is specifled by an attach descriotion for the I/0 module 
tape_ansli_ with the attach argument “vol_1 -neme a“. The second 
input file is specified by the patnname bs, and thus must be a 
sequential or Indexed file In the storage system. The output 
flle is specifled by an attach description for the 1/0 module 
vflle_ with tne attach argument “bd -extend™. For the I/0 module 
vfiile_s this means that the patfrname is c and the flte is to be 
extended; that Is, output records from the Sort willi be written 
at tne end of the file c (if it already exists). 


{A N followed by a tine feed Is used to continue fhe command 
arguments onto the second tine.) . 


The Sort Description (not shown) wlll be read via the user‘’s 
terminal. 


sort -ids “record_stream_ -target vfife_ a” -of b e-cil 


In this exampte assume that the Input file is = an 
unstructured file In the storage system, with the pathname ae 
The Input file has been specified by an attach description using 
the I/70 moduie record _stream_, which will transform the record 
I/O operations requested by the Sort Into the appropriate stream 
I/O operations for tne target file ae | 


sort -lds “syn_ user_switchrame™ eof b -ci 


In this exampie the input file is attached using the 1/90 
module syn_ to the I/0 switch user_switcnhnames, which must be 
attached and closed. 

Name: merge 


The merge command provides a generatized file merging 
capability, which is speciatized for execution by user sunolled 
parameters. The basic functlon of the Merge is to reac one or 
more input files of records which are in order according to the 
values of one or more key fields, merge (col!ate) those records 
according to the vaiues of those key filelas,s and write 2a single 
file of ordered (or “ranked”") records. Tne Merge has tne 
followlng general capabllitless’ 


(END) 
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Input and output files may be on any storage medium and In 


any fila nraanivyatian? 
qaeey ae tt w& ws awaits @ te WEP we wt 
Very large filess such as multisegment files, can be merged$ 


Multiple key flelds and most PL/I string and numeric data 
types may be specified; 


Exits to user supplied subroutines are permitted at several 
points during tne merging process. 


In addition to arguments to the merge command, other 
Information Is necessary to specialize the Merge for a particular 
execution. This information, called the Merge Description, can 
be supplied either through the user*s terminal or In a secment. 


The description given here of the merge command is 
sufficient for situations where the Merge is free standings that 
Is, where no user supplied procedures are executed. (User 
supplied procedures are called “exit procedures™”.) Additional 
information Is necessary for executing the merge command wlth 
exlt procedures, and is contained In the deserliption of the 
merge_ subroutine In the Muitics Programmers® Manual, 
Subroutines, Section IT. 


INPUT ANDO OUTPUT 


The user specifles the input and output files. The Merge 
reads tne input files and writes the output fille. Each input or 
output flie may be stored on any medium and In any file 
organization supported by an I/0 modute through I[ox_. The I/0 
module may be one of the Muitics system I/0 modules (such as 
tape_ansl_})», or one supplied by a specific Instattation, or one 
written by ausere An input or output fllie is specified either 
by a pathname or by an attach description. 


In all caseS, records may be elther fixed ftength or variable 
fengthe 
KEY FIELDS 

Tne user can spacify the key fleids to be usea In ranking 
records. Key fields are described In the Keys statement of the 
Merge Descriptlone Up to 2 key fields may be specified. Any 
PL/I string or numeric deta type - except complex or plctured - 
may be specified for a given key field. Ranking may be 

(END) 
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ascending, descending, or mixeds. For a character string field, 
the collating sequence is that of the Multics standard character 
set. The recoras of eacn inpuf fiie must be in order according 
to tnose key fleltds. 


Aiternatively, the user can specify a user supptled compare 
procedure, which is then used to rank recordse The records of 
each input file must be In order according to the atgoritrm of 
fhat procedure. 


The original order of records with equal keys is preserved 
(FIFO order). Original Input order is defined as foliows? 


ie If two equal records come from dlfferent input files, then 
the record from the flle which is specified eartier In the 
command line is first. 


2s If two equal records come from the same inout file, then the 
record which is earlier In the file is first. 


EXITS 


The Merge provides exits to user supotled procedures at 
specific points during tne merging process. Exit procedures are 
named in the Exits statement of the Merge Oescription. Tne 
following exit points are provided? 


output _record To perform special processing for each output 
record, such as deleting, insertings or 
aitering records to be output from the Merge; 
or summarizing data by accumulating it into a 
summary recorde 


compare To compare two records; that Is; to rank them 
for the merging process. 
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merge 


merge input _specs output _spec control _args 


where? 


le 


2s 


input specs 


indicates that tne user is specifying the 
Input files. Up to 210 input files may be 
specified. Each input file specification 
(each Input_spec) may be suppiled In one of 
the following forms? 


-input_filte pathname 


-if pathname 


If an Input file ts in the Multics 
storage system and [Its file organization 
is either sequential or indexed, then it 
may be specifled by its vathname. The 
fille may be either a single segment or a 
multisegment filee The star convention 
can not be usede 


An Input flte specified by a pathname 
will be attached using the attach 
description “vflie_ patnname™. 


-input_descriotion “attach_desc™ 
-ias “attacnh_desc™ If an input file is not in the Multics 


output _spec 


storage system or its fille organization 
is neither sequential nor indexed, then 
it must ode specified by an attach 
descrIiptione The attach description 
must be quoted. The target I/0 mocule 
speclfled vila the attach description 
must support the sequentiail_Input 
opening mode and the tIlox, entry point 
read records 


Patnnames and attach descriptions can be 
intermixed in the inpuft_specs argumenf. 


indicates that the user is specifying the 
output fitee Only one output file can be 
specified. The output fite specification 
(output spec) may be supltiied in one of the 
following forms? 


-output_flie pathname 


-of pathname 


If the outout file is In the Multics 
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storage system and Its file organization 
is sequential, then it may be specified 
by Its pathname. The file may be elther 
a single segment or a mulftisegment file. 


Tne equals convention may be used. If 
it Is, if Is apoplled to the patrname of 
the first input file and the first Inrput 
file must be specified by a pathname, 
not by an attach description. 


An output flle specifled by a pathname 
will be attached using the attach 
descriptior “vfile_ pathname”. Thus If 
the flie does not exist, it willl be 
created. If it does exist, if wili be 
overwrittere 


-output_description “attach desc™ 

“ods “attach _desc™ If the output file is not In the Multics 
storage system or its flle organization 
is not sequential, then it must be 
specifiec by an attach description. Tne 
attach description must be quoted. The 
target I/0 module specifled vie the 
attach description must support the 
sequential _outout opening mode and the 
lox. entry pcint arite_record. 


controi_args | must be chosen from the following? 


-console_input 

“ci indicates that tha Merge Description is 
read via the I/0 switch user_input 
(which normally is the user’s terminal). 


-merge_desc md_path . 

-md md_path indicates that tne user Is specifying 
the pathname of the segment contalning 
the Merge Description. 


Either the -console_Input or the -merge_aesc 


argument - but not both - must be specified. 
See tne heading Merge Description belowe 
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NOTES 


Arguments can appear In any order, but a pathname or attacn 
description must immedlately follow Its keyword. 


The Merge Description pathname (md_path) is the name of a 
segment. 


Any pathname may be relative (to the user*s current working 
directory) or absolute. . 


(END) 
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The Merge Description contains additional information to 
specialize the Merge for a particular execution. The information 
Supplied may be: 


Keys - Description of one or more key fleids used (for 
ranking records. 


Exits - Specification of which exit polnts are to be used 
and the names of the corresponding user suppliled 
exlf procedures, 


A Merge Descriotion is required. As a minimum, the user 
must specify how records are to be ranked, elther by describlng 
key fields in the Keys statement or by naming a compare exit 
procedure in the Exits statement. Other information in the Merce 
Description Is optional. 


The Merge Description may be supplied as a segment or read 
vila the I/0 switch user_input (normally tne user’s terminal). 


If the Merge Description is supplied in a segment, its 
pathname is specified in the -merge_desc argument. 


If tne Merge Description is read via the user's terminal, 
the econsole_input argument Is used. The Merge eprints “Input?™ 
via the I/0 switcn user_outputf and waits for Input. Tne user 
then tyoes the Merge Descrinotion. To terminate the Merce 
Descriptions, the user types a tine consisting of a perlod (".") 
followed by a line feeae. (This line is not opart of the Merge 
Description.) 


SYNTAX OF THE MERGE DESCRIPTION 


A Merge Oescription consists of a set of statements. Each 
statement must begin witn a function keyword. The function 
keyword is foltowed by the function keyword delimiter colon 
q"3"). The statement itself consists of one or more parameters, 
separated oy parameter deilmiters. Tne parameter delimiters are 
spaces, commas ("y"), or (in certain specific cases as specified 
below) parentheses ("(" and “)™"). Each statement must end wlth 
the statement delimiter semicoton ("3"). 


In the descriptions below, certain notational conventions 
are uSe@de A word enclosed between the tess fhan and greater than 
symbois ("<" and “>") Is a notatlonal variable, which must be 
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replaced by an actual word or phrase of the Merge Description 

enciosed Setwsen < and > is an acTtuai word 
of the Merge Description language. A phrase enciosed bdetween 
brackets ("f° and “J") Is optlonal. A phrase enctosed batween 
braces ("C{" and “}") and followed by an etltinpsis ("see") is 
reaulred, and may be repeated one or more timese 


+ ~ 
language. A word not enciosed betus 


KEYS STATEMENT 


The Keys statement specifies «ey fleids used to rank the 
records of the input files. The format of the Keys statement is: 


keyst {<key_descrlptlon>} ees 3} 

The Keys statement consists of a serles ‘of one or more 
<key_descriptilon>s. The key descriptions are soecifled In order, 
the first describing the major key and the last describlng the 
most minor keye Up to 20 key descriptions nay be supplied. 


A key description is the speclificatlon of a single key 
field. The format of a <key_description> Is? 


<datatype> (<size>) <position> [descending] 


where? 

1e <datatype> is the data type of the key field. Thls 
element Is required. See the table beftow for 
the encoding of <datatype>. 

2e <slze> Is the slze of the key fletd. This element 


is required. 


For string data types, <size> is the length 
{characters or bits) of the fleide The 
fengtn Is the exact amount of space occupnled 
by the fleid. 


For arithmetic data types, <size> Is _ the 
precision (binary or decimal digits) of the 
field. Scale factor, If anys must not be 
written (it is not required by the Merge). 
The space occupled Is determined by the 
precision In combination with the data type 
and the alignment. (Alignment is specified 
via <position>.) For an aligned binary field 
{fixed or floating), the space occupied Is 
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Se <position> 
<> 
<w> (<p>) 
4. descending 
asc 


merge 


increased If necessary to an Integral number 
of words. 


<size> must be a decimal integer. The unit 
depends on the data type. See the tabie 
betow for the semantics of <size>. (The 
rules used are the same as those used by 
Multics PL/I.) 


is tne offset of the beginning of tne key 
field, relative to the beginning of the 
record. Consider the record as being aligned 
on a word boundary, as will be the case for 43 
Multics PL/I structure. Tnis element is 
required. There are two formats? 


where <m> is tne word offset. Words 
are numbered from 0 for the first word 
of the record. This format specifies to 
the Merge that the key fleld is atlgned 
on a word or (if <w> Is even) on a 
double word boundary. 


where <w> is the word portion of § fthe 
offset and <b> Is the bit portion of the 
offset; that Is, the bit offset within 
the word. ‘Bits are numbered from 9 to 
35 This format impties that tre key 
field is not aligned on a word boundary. 
If the key fleid Is aligned on a word 
boundary but the user specifles a bit 
offset of 90 anyway, the Merge wlll 
operate correctly although speed of 
execution may be affected. 


The formats for <position> and the vatues for 
<w> and <b> are consistent with those shown 
ln Multics PL/I listings or used by debug. 


specifies descending order for ranking using 
this key fleld. This element may be omltted; 


the default is ascending order for tris key 
field. 
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DATATYPE ENCODING AND SEMANTICS OF SIZE 


Encoding { Semantics of <si ze> 


of } (where <silze> = n) 
<datatype>! Unlt Range Space Occunled 
Character string char 9 bit 41 - 4095 on characters 
(Muttics ASCII) character 
Blt string ‘ : bit 1 bit i - 4095 on obits 
Flxed binary bin 4 bit 4° 71 Ailgned’ 
1<ns 353 one wore 
36 < nN €< 712 Two wore 


Unatigned: n+#+iz obits 


Floating binary float bin 1 bit 1 - 63 Altloned? 
1 en €£ 273 one wor 
36 <£ n «£ 63% two orc 
Unalianed! n+ Q = 
Fixed decimal dec 9 bit 4° 59 n+ i digits 
(leading sign) digit 
Floating decimal float dec 9 bit 4° 59 n+ 2 digits 
digit 


2 MEN ES Re EEE HARE DERE: SCREEN RR ogg CTS EES aa EE GY a GRY AE eS SEP AEE ie sake 


In addition to the forms shown for <datatype> in the table 
above, tne following variants are also peraltted? 


The following alternate spellings may be used? 
charicharacter binioinary decidecimal 

The word “fixed” may be used (or omitted). For example’ 
fixed bintbdIn fixed decidec 


The words may be written in any sequencee For example? 


(END) 
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EXAMPLES OF KEY DESCRIPTIONS 


char(iG), 04418) Character string, Multics ASCII code, 
ten characters; starts at bit 18 of 


char(8), @, descending 


Character string, Muitics ASCII code, 
eight characters; starts at bit 0 of 


ranking is descending. 


character (4&)- GG» dsc 


Character string, Muitics ASCII code, 


merge 


length 
word Qe 


length 
word 035 


length 


four characters} starts at bit 0 of word 03 


ranking is descending. 


blt{i6), 042) Bit string, length 16 bits$ 


of word 0. 


binti7)ds 2 Fixed binary, precision 


offset is specified, 


occupies one word {equivafent 


amy _ 


bin(i7), 218) Fixed bolnary, preclsion 
offset Is speclfied, 


starts at blt 2 


no obit 
and thus 
“pbin(35), 


a olt 


unaligned and 


occupies 18 bits; starts at bit 18 of word 2 


(ie@ses is in the low order half of 


word , Z)e 


unaligned and thus 


occupies 2 bits$} starts at bit 0 of word 2. 


and thus 


occupies one word (equivatent to “bin(35), 


binli)s 2¢6) Fixed binary, precision 13 

bin{ils 2 Flxed binary, preclislon 13 
age 

bin(36), 2 Fixed blnary, precision 


no olt 


offset is specified and precision is greater 


than 35 and word offset Is even, 


and occupies two 
"“bint71).5 2”). 


dec(6), 919) Flxed decimal, 9 obit 
starts at bit 9 of 


diglts Including slgn (that Is, 


and of word 1). 


float dec(9), g(9) Floating declmal, 9 bit digit, 


allgned 
(equivalent to 


precilslon 63 
word 0 and occuples 7 
through the 


precision 93 


starts at bit 9 of word Q and occupies i1 
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digits inctuding exponent and sign (that Is» 
through the end of word 2). 
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EXITS STATEMENT 

An Exits statement speclfies the exlt procedures to be used 
during execution of the Merge. The format of an Exits statement 
Is 

exits? ‘{<exit_description>} eee 3 

The Exlts statement consists of a set of one or more 
<exit_descriotion>s. Exlt descriptions may be specifled In any 
orders. 

An exit description Is the speclfication of one exlt point 
ang the user supplied exit procedure to be calied at that exit 


point. The format of an <exit_description> Is? 


<exit name> <user name> 


wheres 
te <exit name> is the keyword naming the exit point at which 
the user suppiied exif oerocedure Is fo be 
called. Exif names may be chosen from the 
following tist’ 
output_record 
compare 
2e« user name is the name of the entry point of the user 


suppiied procedure. This parameter has the 
Same syntax and semantics as a command name. 
That is 


User_name can be either a segment name (eeges 
segment) or a segment name and an entry oclint 
name (@egdes segment$entry_ooint). In trese 
cases, the user*s current search rufes are 
appiled to find the oprocedure. (If some 
segment is afready known by the snecified 
reference name, that segment is used.) 


User_name can also be a pathname; that Is- 
can specify a directory hlerarchy tocatlon, 
elther relative (to the user’s current 
working directory) or absolute. In this 
CaSe@y the search rules are not applled and 
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the pathname is used to find the procedure. 
(If some other segment Is already known by 
the specified reference name, that segment is 
terminated first.) 


WRITING EXIT PROCEDURES 


The exit polnts to be used during an execution of the Merge 
and the names of the corresponding user supnoiied exit procedures 
are specified in the Exits statement as described above. Tne 
specifications for writing exlt procedures (PL/I dectare and call 
Statements) and the functional requirements imposed upon exit 
procedures are given In the description of the mercge_ subroutine 
in Section II of MPM Subroutines. 
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Examples 


merge cif mergeein_i cif mergeein_2 -output_file =.out -cl 
Inpute . ; 
key? charligtdes 63 


In this example, the arguments of the command state that 
there are two input files, whose pathnames are mergeein_1 and 
mergesin_2;3 the output file pathname Is merge.out; and the 
Merge Description is input vla the user’s terminal. 


The Merge Description states that there is one key, a 
character string of tength 10 characters, starting af word 0 bit 
0 of the record. There are no exlts specified. 


merge crinput_file ini -if in_2 <-of out_i -merge_desc md 


In this example, the arguments of the command state that the 
input files are named in_1 and in_25; the output file is named 
out_is and the Merge ODescriptlon is contained in the segment 
named mde 


Assume that the segment md contains?’ 


keys fixed bin(35) 0, char(8) 13 
exifs: output_record user$output$ 


The Merge Description states that there are two keys. The 
major key is an aligned fixed binary fieid of precision 35, 
contained in word 0 of the record. The minor key IS a character 
string of length 8, contained In words 141 and 2 of the record. 


Tnere is one exits, an output_record procedure exit; the 
output_record exlt procedure entry point 15s named userfoutput. 


merge -input_description “tape_ansi_ vol_i -name a“ -if b \ 
-output_description “vfile_ c eextend™ -cl 


In this example, there are two input files. The first Input 
file is specified by an attach description for the I/0 module 
tape_ansi_ with the attach argument "“vol_i -name a“. The second 
input file is specified by the pathname by, and thus must be a 
sequential! oor indexed file in the storage system. The output 
file is specified by an attach description for the I/0 module 
vfile. with the attach argument “c -extend™. For the I/0 module 
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vfile_, this means that the pathname Is c and the file Is to be 
extended; that Is, output records from the Merge willl be written 
at the end of the file c (if it already exlsts). 


{A \ followed by a tine feed is used to continue the command 
arguments onto the sscond line.) 


The Merge Description (not shown) wlil be read from the 
user's terminal. 


merge -lids “record stream_ -tarset vfllie_ a” \ 
“ids “syn. user_switchname™ -of c -console_input 


In this example, assume that the first Input file Is an 
unstructured file In the storage system, with the pathname a. 
This input fite has been specified by an attach description using 
the I/0 module record stream» which will transform the record 
I/O operations requested oy the Merce into tne appropriate stream 
I/Q operations for the target flie a. The second input file Is 
attached using the I/0 module syn. to the 1/0 switch 
user _sSnitchnames, which must be attached and ciosed. 


Namet sort. | | 


The sort. subroutine provides a generalized file sorting 
capablilty, which Is speclatized for execution by user supplied 
Parameters. The basic function of sort_ is to read one or more 
Input files of records which are not ordered, sort those records 
according to the values of one or more key fleids,» and write a 
single output file of ordered (or “ranked”) records. The sort 
subroutine has the following general capaoilitiest 


Input ana output files may be on any storage medium ana in 
any file organization} 


Very targe files, such as multIisegment filles, can be sorted; 


Multiple key flelas and most PL/I string and numeric cata 
Types may be specified; 


Exits to user supplied subroutines are permitted at several 
points during the sorting process. 


The arguments to the sort_ subroutine include one or more 
pointers to additional information necessary to specialize sort _ 


for execution. This additional information Is called the Sort 
Description. 
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INPUT AND OUTPUT 


The user can specify the Input and output flies. In this 
environment, the Sort reads the Input files and writes the output 
file. Each input or output fille may be stored on any medlum and 
in any file organization supported by an I/0 module through iox_e 
The 1/0 module may be one of the Multics system I/0 modules (such 
as tape_ansi_), or one suppitied by a specific installation, or 
one written by a usere An input or output file is speclfied 
eitner by a pathname or by an attacr description. 


Alternatively, the user can supply elther an Input_fite 
procedure or an output_file procedure (or d0th). An input_fite 
procedure Is responsible for reading Inout and releasing records 
to the Sort. An output fife procedure Is responsible for 
retrieving records (ranked by the Sort) from the Sort and writing 
output. 


In all cases, records may be either fixed ftength or variable 
lengthe 


a 


KEY FIELDS 


The user can specify the key flelds to be used in ranking 
records. Key fields are described in the Keys statement - or in 
the keys structure - of the Sort Deserlotione Up to 20 key 
flelds may be specified. Any PL/I string or numeric data type - 
except complex or pictured =- may be specifled for a glven key 
fielde Ranking may be ascending, descending, or mixed. For a 
Character string key fletd, the coltfating sequence is that of the 
Multics standard character set. 


Alternatively, the user can supply a compare procedure, 
which is then used to rank records. 


The orlginal inout order of records with equal keys Is 


preserved (FIFO order). Original Inout order Is defined as 
follows? 
Le If two equal records come from different Input filles, then 


the record from the flie which is specified earlier in the 
list of input files Cin the input specs subroutine argument) 
is first. 

Qe If two equal records come from the same inout files then the 
record which is eartier in the flle Is first. 
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EXITS 


The Sort provides exits to user supptied procedures at 
speciflc points during the sorting orocess. Exit procedures are 
Named in the Exits statement - or in tne exits and to_exits 
structures - of the Sort Description. Tne following exit points 
are provided’ 


input_file To obtain Input records and release them one 
by one fo The sorting process. 


output_file To retrieve ranked records one by one from 
the sorting process and output them. 


input_record To perform special processing for each Input 
record, such as deleting, Insertings or 
altering records to be input to the Sort. 


output_record To perform special processing for each output 
record, such as deleting, inserting, or 
aitering records to de output from the Sort; 
or summarizing data by accumulating it Into a 
summary records 


compare To compare two records; that Is», to rank them 
for tne sorting process. 


Detaiis of exit procedures are given below under the heading 
Writing Exlt Procedures, 
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dcl sort. entry((*)cnar(*), char(*), (*)otfr, char(*), 
char (*), float binl€27), fixed bin(35))3 


cali sort. {input_specs, output_spec, sort desc, temp_dirs 
user_out_sw, file size, coded 


where’ 


1. input_specs is an array containing the specifications of 
the input fillese Up to 10 input flies may be 
specified. The array extent specifies the 

number of Input files. (Input) 


Input file J Is specified in the array 
element input_specs(]), In one of the 
followlng forms? 


-input_filte pathname 

-if pathname If an Input fille is In the Multics 
storage system and its fille organlzatlon 
is either sequential or indexed, then it 
may be specifled by its pathname. The 
flie may be elther a singfe segment or a 
multisegment file. The star convention 
can not be used. 


An Input fite specified by a pathname 
will be attached using the attach 
description “vfile_ pathname™. 


-inoput_descrlotion attach_desc 

-ids attach_desc If an input fite Is not in the Multics 
Storage system or its flle organization 
is nelther sequential nor Indexed, then 
it must be specified by an attach 
description. The target I/o0 module 
specified via the attach descrinotion 
must support the sequential_Iinput 
opening mode and the lox_ ertry point 
read_recorde 


Patnnames and aftftacn descriptions can be 
intermixed in the input _specs array. 


If the user is supplying an input_file exif 
procedure, fhen input _sSpecs(i), the first 


(ENO) 


Page 38 


sort_ 


2s 


outpuft_ spec 


-output_file pat 
-of pathname 


-output_file “re 
“of -rp 


-outpuf_descript 
-ods attach_desc 


sort. 


Oe ae 


input file specification, must be “" (the 
array extent should be 1) and the inout_flie 
exit orocedure must da named in the io_exits 
structure of the Sort Description. 


is the speclfication of the output filee 
Only one output file may be specified. 
(Input) 


Tne output file may be specifled in one of 
the following forms: 


Aname 
If the output fille is In the Multics 
storage system and its file organization 
is sequential, then it may be specifled 
by its pathname. Tne file may be eltner 
a single segment or a muitisegment file. 


The equais convention can be usede If 
it is, it Is appiled to the pattname of 
the first input file and the first Irput 
file must be speclfled by a pathname, 
not by an attach description. 


An output file specified by a pathname 
willl be attached using the attach 
description “vflie_ pathname". Thus if 
the fille does not exist, if will be 
created. If It does exist, it will be 
overwrittene 


place 
The output file is to replace the first 
input file. Tnat Input file wlll be 
overwritten during the merge orase of 
the Sort. If -erepltace is used, the 
first inout flle must be specified by a 
pathname, not by an attach descriotilon.e 


Lon attach_desc 
If the output fille Is not in the Muitics 
Storage system or its fite organization 
is not sequential, then it . must be 
specifiec by an attach description. The 
target I/0 module specified via the 
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sort _desc 


temp_dir 


user_out_sw 


attach description must support 
sequential _output opening mode ana 


iox. entry point write record. 


If the user is supplying an output_fille exit 
procedure, then the output spec argument must 
be “" and the output_file exit procedure must 
be named in the io _exifs structure of the 
Sort Description. 


is an array of pointers to the Sort 
Description. See the heading Sort 


Description below. (Input) 


Is the pathname of the directory which willl 
contaln the Sort"s work filles. (Input) 


If this argumert Is ™", then work files wlll 
be contained in the user’s process dlrectory. 


This argument should be used when the process 
directory will not be large enough to contain 
the work flies. The get_wdir_ function may 
be used to obtain the name of the users 
current working directory. 


specifies the destination of both the summary 
report ang diagnostic messacses for errors 
detected in the arguments to sort_ or in the 
sort Description. (Input) 


This argument may have the following values’ 
bac = write the summary report and 


diagnostic messages via the I/0 
switch user_output. 


"<b f™ do not write the summary report 
and dlagnostic messages. If any 
errors are diagnosed, sort, will 
return with the status code 
bad_arg but information about 
the number and nature of the 


errors Is not avallablie. 


iT) 


write the summary report and 
dlagnostic messages via the I/0 
switch named switchname. The 


switchname 


(END) 
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switch must be attached and open 
for stream outpute 


6. tiie size is tne total amount of data to be sorted, iin 
mitilons of bytes. If this argument is zero, 
the default assumption Is approximately one 
midlion bytes (file _size = 1209). (Input) 


This argument is Intended for use when some 
or all of the input files are not In the 
storage system (that is», are not specified by 
Datnnames) or when an input_file exit 
procedure Is used. In these cases the Sort 
cannot determine tne amount of input data. 
{The Sort does compute the total amount of 
input data which Is In the storage system, 
using segment oif counts.) The file size 
argument may also be used when all of tre 
input fillies are In the storage system but 
records are fo be Inserted or deleted trrough 
an input _record exit procedure. 


The fliie_size argument is used for 
optimization of performance} the actual 
amount of data can be considerably targer 
without preventing the Sort from completing. 
The maximum amount of data which can be 
sorted is (in bytes) approximateiy 69 miilion 
times the square root of file_size. 


fe code is a standard Multics status code refurnec by 


sort_. Possible values are tisted below 
under the heading Status Codes. (Outout) 


NOTES 
The temporary directory pathname (temp_dir argument) is the 
name of a directory. 


Any pathname may be retative (fo the user"*s current working 
directory) or absolute. 


STATUS CODES 


The foltfowing status codes may be returned by sort. (all 
codes are in error_table_)3 : 


(END) 
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fatal_error 


out_of_sequence 


sort_ 


rere aioe anes eres 


Normal return (no errors). 


One or more arguments specifled to sort_, 
Including those In the Sort Descriptlon, was 
iInvatid or inconsistent. The Sort wlll § tave 
previously written diagnostic messages as 
directed by the user_ouft_Sw argument. The 
sorting process itself has not been started. 


The Sort has encountered a fatal error during 
the sorting orocesse The Sort wlll have 
prevlousiy generated a specific error message 
and signalied the sub_error_ condition via 
the sub_Lerr_ subroutine. 


The call to sort. is not In the sequence 
required by fre Sorts That is» sort. has 


been called after Inltiation of the Sort obut 
before termination of that invocation. 


(END) 
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Sort Deseriotlon 


The Sort Description contains additional Information to 
specialize the Sort for a particular execution. The Sort 
Description is specified via the sort _desc argument to sort_e 
Tne information specifled may be3 


Keys - Description of one or more key fields used for 
ranking records. 


Exits - Specification of which exit polnts are to be used 
ana the names of the corresponding user sunpiled 
exif procedures, 


A Sort Description Is required. As a minimum, the user must 
specify now records are to be ranked, eltner by describing key 
fieids in tne Keys statement or ody naming a compare exit 
procedure In the Exits statement. Other Information in the Sort 
Description is optional. 


The Sort Oescriptlon may be suppiied to sort. in either of 
two forms, calied source form and internal form. 


The source form of the Sort Description Is written exactly 
as specified for the sort command (see the Multics Programmers’ 
Manual, Commands and Active Functlons, Section III), and is 
stored as an ASCII segment$; that Is, as an unstructured file in 
the Multics storage systems» If source form is useds then the 
sort _desc argument to sort. musf have an array extent of 4 and 
the one pointer must be a polnter to the segment. (Tne segment 
must contain only the Sort Description.) The source form is 
useful when the user writes the Sort Descriotion and suppiles If 
to the procedure which calits sort_.- 


The internal form of the Sort Description is a set of one to 
three structures. The sort_desc argument must hsve an array 
extent of 3, and the three pointers are pointers to the _ ftfrree 
structures. Any of the structures can be omitted; In that case 
the corresponding pointer must be null. The pointers must be 
specified in the array in the following order: 


adar (keys) 
addrfexits) 
addr(io_exits) 
where the three structures (keys, exits, and tlo_exits) are 
defined below. Tne internal form ls useful when the procedure 
caliing sort. constructs the Sort Descrlption. 
(ENO) 
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KEYS STRUCTURE 


The keys structure Is used when the calter describes key 
fields. The Sort*s standard compare routine wlll then be used to 
rank recordse If the caller describes keys, then the compare 
exit must not be specified. 


If the caller does not describe keys, then the corresponding 
pointer In the array sort desc must be nuli and the compare exit 
must be specifled in the exits structuree The user supptled 
compare routine will then be used to rank records. 

The keys structure is? 


dcl 4 keys, 


2 version fixed bln init(4), 
2 number fixed bin, 
e key_desc(user_keys_ number refer(keyse number) ), 
3 datatyoe char (6), 
3 size fixed bin(24), 
3 word_offset fixed bint15), 
3 bit_offset fixed bin(6), 
3 desc char (3) 3 
where? 
1 verslon is tne version number of the structure (must 
be 1). 
2~e« number is the number of key flelds, estabilshed by 


the vaiue of user_keys_number. 


30 key_desc is an array of key descriptions. Each key 
dgescriotlon is one element of the array. The 
key descriptions must be specified In order, 
the major key first and the most minor key 
last. 


&e datatype is the data type of tne key field. See the 
Table below for the encoding of datatype. 
The value must be teft Jjustifled within 
datatype. 


5. size is the slilze of the key fletd, In units whlch 
depend on the data type. 


For string data types, size is the exact 
length (characters or bits) of the fleld. 


(END) 
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8. 


word offset 


bit_offseft 


desc 


For arithmetic data types, size is the 
precision (binary or decimal digits) of the 
fieid. The space occupled is determined by 
precision in combination with the data type. 
The space occupied is not adjusted for an 
aligned field. For example, for an allgned 
fixed binary field of one word, size must be 
specified as 353 for an atlignea floating 
binary field of two words, slze must be 
specifled as 63. See the fabie befow for the 
semantics of size. _ : 


is the word portion of the offset of the 
beginning of the key fleld,s relative to the 
beginning of the record. Consider the record 
as being aligned on a word boundary, as wilt 
be tne case for a Multics PL/I structure. 
Words are numbered from 0 for fhe first word 
of the record. 


is the bit portion of the offset of the key 
fleld; that is, the bit offset witnin fhe 
word in which the key field begins. 8its are 
numbered from G to 35. (If the fleltd ts 
aligned on a word boundary, then bit_offseft 
is 0-2) 


Indicates whether ranking for this key fleida 
is to be ascending or descending. Possible 
values aret 


use ascending ranking. 


T) 


use descending rankinge 


a8 dsc™ 


(END) 
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DATATYPE ENCODING ANDO SEMANTICS OF SIZE 


Encoding | Semantics of size 
of of | (where size = n) 
datatype ! Unit Range Space Occupled 
Character string char 9 bit 4° 4095 nn characters 
(Multics ASCII) character 
Blt string bit 1 bit 4 - 4095 on oblts 
Fixed binary bin 1 bit 1-71 n+i obits 
Floating binary fibin 4 bolt 1:* 63 n+ 9 oblts 
Fixed decimal dec 9 bit 1 - 59 n +1 digits 
(leading sign) digit 
Floating decimai fildec 9 bit 1 - 59 n + 2 digits 
digit 
(END) 
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EXITS STRUCTURE 
Tne exits structure is? 


dcl 1 exits, 


41 version fixed bin init(1), 
2 compare entrys 
2 input record entry, 
2 output_record entry; 
where? 
1s version is tne version number of the structure (must 
be 1). 
2. compare specifles the entry point of a user suopnlied 
' compare exit procedure. If the caller 
describes key fleitds (supplles a keys 
structure), then this exit must not be 
specified. 
3e Input record specifies the entry polnt of a user. suppiled 


input_record exlt oproceduree This exif can 
pe specified whether or not the input_file 


exit is specified. 


4-e output_record specifies the entry point of a user suppiied 
output _record exit procedure. This exif can 
be specified whether or not the outnout_file 


exit is specified. 


IO0_EXITS STRUCTURE 
The lo _exits structure Is? 


dcl 4 lo_exits, 


2 version | fixed bin Init(i), 
2 Input_file entrys 
2 output_file entry; 
wheres 
ie verslon Is the version number of the structure 
be i). 
(END) 
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2e Input_file specifies the entry point of a user supplied 
inout_fifte exit procedure. if the caller 
names Input files, then thls exit must not be 
specifled. 


3. output_file specifies the entry point of a user suppliled 
output_file exit procedure. If the caller 
names the output file, then this exit must 

not be specifiede 


ENTRY VARIABLES 


In the exits and io exits structures, each exit polnt Is 
specifled vila an entry varlable. The entry varlable must be set 
(elther Initialized or assigned) by a user procedure, normatty 
the procedure which calls sort. The entry variabie can identify 
elther an internal entry point (that Is, an Internal procedure) 
or an external entry point of the procedure which sets the entry 
variable; or it can identify an external entry point of another 
user porocedure@e 


If none of the aeaxits declared In elther the exits or 
lo_exits sfructure is to be used, then fhat structure can be 
omitted and the corresponding polnter In the array sort_desc must 
be null. If the structure is Included but an exit specified in 
it is not to be used, then the corresponding entry varlable must 
be set to sort_$noexlit, which is declared? 


dcl sort_tnoexit entry external; 
An exit point may not be aitered after the cal! to sort_. 
Any change to the entry variable fhereafter wllt have no effect. 


However, certain entry polnts can be disabfed, as specifled In 
the descriptions of the individual exit procedures below. 


(END) 
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Weiting Exit Procedures 


A user supplied exif procedure is catied by the Sort to 
perform a specifled functlon.. The user procedure must perform 
that function, and then must return to the Sort. The user exlt 
procedure may perform additional functions desired by tne user. 


Certain exit procedures replace the corresponding standard 
routine of the Sort. Other exit procedures Supptement the normal 
functlons of tne Sort. This is specified for each indlvidual 


exit procedure below. 
Tne following exit points are provided: 


input_file 
output_file 
compare 
input_record 
output_recorad 


Ail exit points may be active auring the same Invocation of 
the Sort. 


The entry point names of all user supptied exit procedures 


are defined by the user. Speclfic names are shown below orly for 
convenience in discussion. 


(END) 
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INPUT_LFILE EXIT PROCEDURE 


An input_fite exit porocedure replaces the standard Inout 
reading function of the Sort. The Sort catis the Input_flle exit 
procedure oniy once during an executlon of the Sort. 


An input_file exit procedure must operform the following 
function: For each record which is Input by the user to the 
sorting process, the Input _file exit orocedure must make one call 
to the entry sort _trelease (descrlbed tfater). After the 
iInput_flle exlt procedure has released the last Input record to 
the Sort, it must return fo the Sort. 


Usage 
input_file?  proc(code)§ 
-dcl code fixed bln(35) parameter; 
where code is a standard Multics status code (in error_tablie_) 
which must be returned by the input_flle exit procedure. If the 
value is not Q», than the Sort normatliy prints the corresponding 


message and returns to ifs catter with the status code 
fatal_error. (Output) 


(END) 
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OUTPUT_FILE EXIT PROCEDURE 


An output_file exit procedure replaces the standard output 
writing function of the Sorte The Sort calls the output_flie 
exit procedure oniy once during an executlon of the Sort. 


An output_file exit procedure must perform the following 
functions: For each record which is to be retrieved in ranked 
order from the Sort, the output_file exif procedure must make one 
call fo the ‘entry point sort $return (described fater). If 
sort_$return is caited but there are no more records’ to be 
retrieved from fhe sorting process, then sort_freturn returns 
wifh the status code end_lof_info. The outpuf_file exit orocedure 
then must return to the Sort. If the user desires, the 
output_file exit procedure may terminate retrieval at any time 
prior to recelving the end_of_info status, but It must stiit 
return to the Sort. (The entry sort_$return may return status 
codes other fhan end_of_info in case of error.) 


Usage 

output_file: proc(code)$ 

dc! code fixed bin(35) parameter} 
where code is a standard Multics status code {in error_tabie_) 
which must be returned by the output_flie procedure. If the 
value is not 9+ then the Sort normally orints the. corresponding 


message ana returns to its cailter with the status code 
fatai_error. (Output) 


(END) 
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COMPARE EXIT PROCEDURE 


A compare exit procedure replaces the standard record 
comparison procedure of the Sorte The Sort calts the compare 
exit procedure each time fhe sorting process Is ready to rank two 
records; that is, to determine which of the two is first in the 
sorted order. 


A compare exit procedure must oerform the following 
function: The compare exit procedure receives as arguments a 
polnter to each of the two recordse The compare exit procedure 
must determine which of tne two records Is first - or that they 
are equal in rank - and must return a corresponding return value 
to the Sort. Tne compare exit orocedure Is Invoked as a 
functione 


Usage 


compare: proc(rec_ptrii, rec uptr_2) returns(fixed bin (1))3$ 


del (rec_ptr_i ptr, 
rec _ptr_2 ptr) parameter 5 
del resuit fixed bint1)3 


return(resul t) $ 
end compares 


where’ 

1. rec_ptr_i is a pointer to a dounvie word aligned ouffer 
containing the first record of the palr to be 
compared. This record is always the first of 
the two according to the original Input 
order. (Input) 

250 rec_ptr_2 -is a pointer to a dountie word aligned buffer 
containig the second record of the palr to be 
compared. (Input) 

3. result is the result of the comparison. (Output) 


Possible values are? 


0 = the two records rank equal. 


(END) 
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“1 = the record pointed to by rec_ptr_1i ranks 
first. 
#4 = the record pointed to by rec_optri2 ranks 


first. 


If a compare exit procedure requires the fength of either 
record, lt is availabie in the word preceding that record in the 


form? 
dcl rec_ien fixed bin(21) aligned; 


A compare exit procedure cannot atter either the content or 
tne length of eitner record. 


(END) 
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INPUT_RECORD EXIT PROCEOURE 


An Input record exit procedure may be used whetrer the 
Sort’s standard input_filtle procedure or a user supotiled 
Input_file exIlt procedure Is used, and supplements that 
Input_file procesSe The Sort calls the Input record exit 
procedure?’ 


1» Each time the iInput_file process releases a record to _ the 
Sorts and before that record is entered into the sorting 
processs 


Ze Once more after the last Input record has been released to 
the Sort (end of Input); 


3e Additionailys, each time the Input record exit procedure 
returns with an action of insert. 


The Sort gives the input _record exit procedure access to the 
current record, the record about to be entered Into the sorting 
procesSe 


An Input record exit procedure need not perform any 
processinge If it does nof, then tne Sort wlll accept the 
current record Into the sorting process. 


An Input_record exit procedure may operform the foltowing 
functions, which are accomplished via the values of arguments 
returned when the Inout_record exit procedure returns to the 
Sorts 


Accept the current record. This is accomplished by settling 
action = 0. 


Delete the current record. This is accomplished by setting 
actlon = i. 


Insert one or more records before the current record. (At 
the fast call to the input_record exit procedure, records 
may be inserted at the end of Input.) This is accomplished 
by setting rec_ptr to point to the record to be _ Inserted, 
setting rec_len appropriately, and setting action = 3. 


Alter the current record, ovoefore it is entered into the 
sorting processes Tnis is accomptished by altering the 
record polnted to by rec_otr or setting rec_ptr to point to 
another record, setting rec_!ten appropriately, and setting 
actlon = QO. 


(END) 
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Ciose the exit polnt so that the inpuf_record exit procecaure 
wlil not be cailed again during this execution of the Sort. 
This is accomplished by setting close_exitisw = "1". 
The input record exit procedure must return to the Sort each 
time it ls called. 
Usage 


input record: proc({rec_ptr, rec lien, action, close_exlt usw): 


del (rec _ptr ptr, 
rec_ien fixed bin(21)>5 
action fixed bin, 


ciose_exit_sw biti) ) parameters; 
where’ 


1. rec lptr polnts to a doudvte word aligned buffer 
containing the current record. The 
input_record exit procedure may alter fthe 
contents of the record or may change fhe 
pointer to point to another record. For the 
actions of accept and insert, tne Sort will 
use the value of rec_ptr returned to if by 
the input _record exit oroceduree 
(Input/Output) 


At the tast cali to the input record exif 
procedure (end of input), there Is no current 
record and rec_otr = null (). 


22 rec_len is the tength of the current record In bytes. 
The input_record exit procedure may change 
the length of the record. For the actions of 
accept and insert. tne Sort wilt!i use the 
value of rec_len returned to if by the 
Input_record exit procedure. (Input/Output) 


32 action Indicates the action to be taken upon return 
to the Sort. (Inout/Output) 


Arguments referred to betow are the vatues 


returned to the Sort by the input_record exif 
procedure. 


(END) 
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close_exit usw 


Posslbie values of actlon aret 


0 = accept the current record. Tne record 
polnted to by rec_ptr, whose flencthr Is 
given by rec_tien, is entered Into the 
sorting processe 


Each time the Input record exit procedure 
is calted, the Sort sets actlon to this 
value. 


4 = delete the current record. The current 
record is not entered into the sorting 
processe 


3 = Insert a record. The record pointed to 
by rec_ptr, whose tength is given by 
rec_len, is entered into the sorting 
processe The Sort calls the Input record 
exit procedure again, so that the current 
record may be accepted or deleted or an 
additlonal record may be Inserted. At 
this next cali to the input_record exit 
procedure, the current record remains the 
Sames 


At the last call to the input record exit 
procedure (end of Input), If the Input_record 
exit procedure Inserts records then they are 
appended at tne end of Input. Any other 
value for action means do not append any 
records, and the input record exit will not 
be taken agaln. 


Indicates whether the exit Ils to be closed 
hereafter. (Input/Output) 


Posslble vaiues are’ 

"9" = keep this exit ooen.e Each time the 
input_record procedure Is calted, the 
Sort sets close_exlt_ sw to this vatue. 

"4" = close this exIlt. The Sort wltt not 
calt' the Input record exit procedure 


again during this execution of the Sort 
(even If the action Is Insert). 


(END) 
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OUTPUT_RECORD EXIT PROCEDURE 


An output _record exit procedure may be used whether’ the 
Sort*s standard output _ file procedure or ae=user sunoptled 
output_file exit procedure is used, and supplements that 
output_file process. The Sort calis the outfput_record exit 
procedure’ 


4 Each time lt nas determined the next record In ranked order 
from the merging process; 


2s | Once more after the fast record nas been obtalned from the 
merging process (end of oufput)3 


3e Additionally, each time the output record exit procedure 
returns with an action of Insert. 


The Sort gives the outpuf record exit procedure access to 
two records? 


1. The output record, about fo be written to the output fite. 
(If an output _file exit procedure has been specifled by the 
user, this is the record about to be returned to that exit 
procedure.) 


2e The next record, fhe record teaving the merging process. 


An output record exit procedure need not perform any 
processinge If it does not, then the output record Is accepted 
for the output fille. 


An output_record exit procedure may perform the following 
functions, which are accomplished via the vaiues of arguments 
returned when the input record exit procedure returns to the 
Sorts : 


Accept the output record. Thls is accomplished by setting 
action = Q. , . 


Celete the output record. This Is accomptished by setting 
action = 1. 


Delete the record teaving the merges This is accomplished 
by setting action = 2. 


Insert one or more records after the output record. (AT the 

first call to the output record exit procedures records may 

be Inserted at the beginning of oufpuf. At the Jast call to 
(END) 
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sort_. 


the output_record exit procedure, records may be Insertec at 
the end of output.) This is accomolished Sy setting. 
rec_ptr_2 to ooint to the record to be Inserted, setting 
rec_ten_2 appropriatelys, and setting actlon = 3. 


Alter the output record, before it is written to the output 
file. This is accomptished by aftering the record polnted 
to by rec_oftr_1 or sefting rec_otr_i to point to another 
record, setting rec_len_i appropriately, and settings action 
= € to accept (or actlon = 3 to Insert). 


Summarize data into the first record of a sequence of 
records with equal keys, and delete the succeeding records 
of the sequence. This may be accomplished as follows’ At 
the first catl to the output record exit procedure, set 
equal key checking on (equal_key_sw = "1"). At subsequent 
calis to the output record exit procedure, if the output 
record and the record leaving the merge have equal keys 
(equal_key = 0), then accumulate data into the output record 
and delete the record leaving the merge (actlon = 2). If 
the two records have unequal keys (equai_key # 90), #4xthen 
accept the output record (actlon = Q). 


Summarize data into the last record of a sequence with equal 
keyS, and delete the preceding records of the sequence. 
This may be accomptished as folfows: At the first call to 
the output_record exit procedure, set equal key checking on. 
At subsequent calis, if the two records have equal keys then 
accumulate data into a work area and deiete the outout 
record (action = 1). If the two records have unequal keys, 
then alter the output record using the accumulated data and 
accept that recora (action = Q). 


Seauence check the outout file. This is accomptished by 
setting seq .check_sw = “4%. If the output record will not 
collate properly with the output file, or does nof nave ifs 
keys in the position specified to the Sort, then set 
seq_check_sw = "9", 


Close the exit point so that the output record exit 


procedure wiii not be called again during this execution of 
tne Sorte. Tnis is accomplished by setting close_exit_sw = 


i 


The output_record exlt procedure must return to the Sort 
time it is called. 


(END) 
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Usage 


output_record: proc(rec_ptr_is rec_len_is rec lptr_2, rec_ten_2, 
actions equal _key, e2quai_key_sw, 
seq _check_Sw, close_exilt_sw$ 


dcl (rec_ptrii ptf» 
rec_len_i fixed bin(21), 
rec_ptr_2 ptr, 
rec_ien_2 fixea bin(2i), 
action fixed bin, 
equal _key fixed binti), 


equal_key_sw bit(41), 
seq_check_s«# bit(1), 
close_exit_sw biti) ) parameter}; 


where? 


1e- rec_ptr_i points to a double word aligned buffer 
! containing the output record. The 
output record exit procedure may aiter the 
contents of this record or may change the 
polnter to polnt to another record. The Sort 
uses the value of rec_ptr_i returned to if by 
the output_record exit procedure as specifled 
below in the description of the action 
argument. (Input/Output) — 


At the first cali to the outpuf_record exit 
procedure (beginning of output)s there Is no 
output record and rec_otr_i = nutlti(d). . 


22 rec _ienwi is the tength of the output record in bytese 
The output_record exit procedure may change 
the lencth of this record. The Sort uses the 
value of rec_len_i returned to It by the 
outputf_record exit procedure as snoecified 
below in the description of the action 
argumente (Input/Output) 


3e rec _ptr_2 points to a double word atigned buffer 
containing the record fieaving the merge. The 
outout_record exit oprocedure may not alter 
the contents of this record. For all actions 
except insert, the Sort will! Ignore the value 
of rec _ptr_2 returned to it by the 
output _record exit procedure. If fhe action 
ls insert, then the output_recorda exit 


(END) 
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rec_ien_2 


action 


procedure must change rec_otr_2 to point to 
the record to be Inserted. (Input/Output ) 


At the last call to fhe outputlrecord exit 
procedure (end of output), there Is no record 
leaving the merce and rec_otr_2 = null (). 


is tne ftengtn of the record teaving the. 


merge@e The output_record exlt procedure may 
not change the fength of this record. For 
al} actions except insert, the Sort will 


ignore the vatue of rec_len_2 returned to It 
by the output _record exit procedure. If the 
action Is insert, then the output_record exit 
procedure must sef rec_len_2 to the lencth of 
the record to be Inserted. (Input/Output) 


indicates the action to be taken upon return 
to the Sort. (Input/Output) 


Possibie values of action are: 


0 = accept the outpuf record. The output 
record Is written to the output flie. 
Tne Sort uses the returned vatues of 
rec_ptr_i and rec_len_i to identify the 
record to be written. At the next call 
to the output_record exit procedure, the 
record leaving the merge becomes the new 
output record, and a new record teaving 
the merge has been obtained. 


Each time the output_record exit 
procedure is caltted, the Sort sets actlon 
to this value. 


1 = delete the output record. No record Ils 
written to the output filee The Sort 
Ignores the returned values of rec_pfr_1 
and rec_lten_i.- At the next call to the 
output_record exlt procedure, the record 
leaving the merge becomes the new output 
record, and a new record teaving the 
merge has been obtained. 


2 = deftete the record leaving the merge. 
(This actlon should be used for 
summarization into the output record.) 


(END) 
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No record Is written to the output file. 
At the next cal! to the output record 
exit procedure, tne output record remains 
Tne same, and a new record fieaving the 
merge has been obtained. The Sort uses 
The returned values of reclotr_i and 
rec_len_i to Identify the output record 
for that next call to the outout_record 
exit procedure. 


3 = Insert a record after the output record. 
The output record is written to the 
output file. The Sort uses the returned 
vafues of reclptr_i and rec_lien_i- to 
identify the record to be arltten. The 
Sort calls the output _record exif 
procedure again, so that the inserted 
record may be accepted or an additional 
record may be Inserted. At this next 
call to the output_record exlt procedure, 
the inserted record becomes the new 
output record, and the record feaving the 
merge remains the same. The Sort uses 
the returned values of rec_lpoptr_2 and 
rec_fen_2 to Identlfy the inserted 
record. _ 


At the fast call to the output_record exit 
procedure {end of output), if the 
output_record exit procedure Inserts records 
then they are appended at the end of output. 
Any other vaiue for actlon means. do not 
append any records, and the output record 
axit will) nof be taken agaln. 


indicates whether the output record and the 
record ftleaving the merge nave equal keyse 
(Input) 


Possibie vatues are: 


0 = the Two records rank equal. 
+1 = the two records do not rank equal. At 
the first and last calls to the 


oufput_record exit procedure (beginning 
of input and end of input), only one 
record Is present and the Sort sets 


(ENO) 
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seq_check_sw 
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equal_key to this value. 


If the user suppiled key descrlotions, then 
the vatue of equal_key is determined only by 
those key fietds}; the orlginal inout order 
of the two records is not used to resolve key 
equality. If the user supptied a compare 
exit procedure, then the Sort uses the result 
of tnat comoare exit procedure to set the 
value of equal_key. (In elther case, If the 
Two records rank equal then rec_ptr_i points 
to the record which is first according to the 
original Input order of the two records.) 


indicates whether or not equal key checking 
is to be performed. (Input/Output) 


posslbfe values are? 


*“9" = do not check for equal keySe At the 
first cail to the output_record exit 
procedure {beginning of output), the 
Sort sets equal_key_sw to this value. 


"4" = check for equal keys before the next 
cali to the output_record exit 
procedure. 


Slnce equal key checking takes time, the user 
should set equal_key_sw = “i™ only when 
required for actions such as summarization. 


indicates whether or not sequence checking is 
fo be performed. (Input/Output) 


Possible values are? 

“o™ = do not sequence checke 

4" = sequence check. At the first calf to 
the output record exit procedure 
(beginning of output), the Sort sets 
seq_check_sw to this value. 

Sequence checking means comparing the outnout 

record to the record oreviously written to 

the output file. (If the user specifled an 

outoput_file exit orocedure, the output record 


(ENO) 
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is compared to the record previously returned 
to that exit procedure.) Sequence checklng 
is performed after the oufputf_record exit 
procedure returns to the Sort, and onty if a 
record is to be written to the output file 
(that Is, only Lif the action IS accept or 
insert). If the user supptiled key 
descriptions, then the Sort*s key comparison 
routine IS used. If the user suoplied a 
compare exit procedure, then that exit 
orocedure is called. 


If the output record is out of sequence wlth 
the prevlous record, then the status, code 
fatal_error is returned to the caller of 
sort_3; see the entry sort_ above. (If the 
user specified an output _flie exit procedure, 
then the status code data _seq_error is 
returned to that exit procedure; see the 
entry sort_$return below.) 


Aii records written to the output files 
Including inserted records, can be sequence 
checked. 


indicates whether the exit is. to be closed 
hereafter. {Input/Output ) 


Possibdie values are? 
"qq" = keep this exit opens Each time the 


output_record exit procedure is calleds 
the Sort sets close_exit_sw to this 


value. 
"4" = close this exlt. The Sort willl not 
call the output_record exit procedure 


again during this execution of the Sort 
{even if the action Is Insert). 


(ENO) 
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RECORD POINTERS 


Since the Sort aligns each record ina buffer on a double 
word boundary, If an exit procedure applles a based declaration 


of the record to the  polinter(s) then correct alignment Is 
ensurede 


ORIGINAL INPUT ORDER (FIFO) 


For the compare and output _record exit procedures, rec_otr_1 
always points to the record whose original Input order was orior 
to the record pointed to by rec_lotr 2. If a compare exit 
procedure returns with an equal ranking for the two records, then 
this original Input order is preserved. Original input order has 
been defined eariler under the heading Key Fields. 


(END) 
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Entry: sort _$release 

Tne entry “sort_$release™ is used each time tne caller 
releases a record fo the sorting procesSe Calls to 
sort_treiease are made from a user supplled Input_file procedure. 


The calier specifies the location and length of the record. The 
Sort accepts the record and stores it In IfS own work area. 


Usage 
del sort_$reiease entry{ptrs fixed bin(21), fixed bin(35))5 


cali sort _$release (ouff_ptr, rec_ien, coded$ 


where? 

4. buff_otr is a pointer to a byte alignea — buffer 
containing the record. (Input) 

2. rec_ien is the tength of the record in bytes. 
(Input) 

3e code is a standard Multics status code returned by 
the Sorf. Possibie vaiues are listed below 
under the heading Status Codese (Output) 

Notes 


The Sort allgns each record on a doudle word boundary in a 
work area. 


atatus Codes 


The foliowing status codes may be returned by the 
sort_$release entry point (ali codes are in error_table_)! 


0 Normal return (no error). 
out_of_sequence The cal! to sort $reiease is not in the 
Sequence required by the Sort; CeGes 


sort _$release has been catied before sorf_. 


(END) 
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long _record 


Short eurecord 


The Sort has encounterd a fatal error during 
the sorting process. The Sort wll! rave 
previousty generated a specific error message 
and signaited the sub _lerror_ condition via 
the subLlerr_ subroutine. 


This input record is fonger than the maximum 
suppor ted. The record is Ignored by the 
sort, and the caller nay continue to release 
records to the Sort. 


This input record is shorter than the mininum 
required to contain the key fields. The 


record Is ignored by the Sort, and the caller 
may continue to release records to the Sort. 


(END) 
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The sort _treturn entry is used each time the caller 
retrieves a record, in ranked order, from tne Sort. Calls to 
sort_$return are made from a user supplied output_file procedure. 
Upon return from sort_$return, the cailer is glven the location 
and jength of the record. 


If sort $return Is cailed but there are no more records to 


be retrieved, then sort_$return returns to the caller with the 
Status code end_of_info. . 


Usage 


dei sort $return entry(ptr, fixed bin(21), fixed bin(35))3 
call sort_$return (buff_ptr, rec lens code); . 


where? 


1. bufflotr is a pointer fo a douote word aligned buffer 
containing the record. (Output) 

2e rec_ien is The tength of tne record in py tes. 
(Output) 

3-2 code ls a stanaard Muitics status code returned by 
the Sort. Possible values are tisted below 
under the heading Status Codes. (Output) 

Notes 


The Sort aligns each record on a doubie word boundary In a 
work area. Thus if the calfer appiles a based declaration of fhe 
recora to the polnter then correct alignment is ensured. 


Status Codes 


The following status codes may be returnedad by the 
sort _$return entry point (all codes are in error_tablie_): 


0 Normal return (not end of Informatlon, no 
error). 


(END) 
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end_of_info There are no more records to be retrieved 
from the Sort. This is the normal end of 
data indicatlone No record is returned to 
the caller. 


out_of_sequence Tne call to sort $return Is not In the 
sequence required dy the Sorts Qaodey 
sort _tsreturn has been called before 


sort _s$release. 


fatal_error The Sort has encountered a fatal error during 
. the sorting process. The Sort will have 
previously generated a specific error message 
and signalled the sub_error._ condition via 
the sub_err_ subroutine. 


data_!oss Ena of data has been reached, but the number 
of records previously returned is tess than 
the number of records released to the Sort. 
No record is returned fo the caller. 


data_galn The number of records returned (inctuding 
thls record) is now targer than the number of 
records reieased fo the Sort. fhe current 
record is returned to the caller, and the 
caller may continue to retrieve records from 
the Sort. 


data_seq_error A ranking error has occurred in the records 
returned to the caller (as determined by the 
key fleids of the record). The current 
record Iis returned to the caller, and the 
caller may continue to request records § from 
the Sorte 


Names merge_ 


The merge. subroutine provides a generalized file merging 
capabillty, which Is specialized for executlon by user suoptied 
parameters. The basic function of merge_ is to read one or more 
Input flies of records which are In order according to the vaiues 
of one or more key fields, merge (collate) those records 
according to the values of those key fleids, and write a single 
output flie of ordered (or “ranked™) records. The merge_ 
subroutine has the following general capabliities? 


Input ana outout files may be on any storage medium and In 
any file organization; 


(END) 
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Very farge files, such as muiltisegment files, can be merged; 


Multipte key fields and most PL/I string and numeric data 
types may be speclfied} . 


Exits to user supplied subroutines are permitted at several 
points during the merging process. 


The arguments to the merge_ subroutine Include one or more 
pointers to additional information necessary to speciaiize merge_ 
for execution. This additional information Is calted the Merge 
Description. 


INPUT AND OUTPUT 


The user specifies the Input and output files. The Merge 
reads the input files and writes the output file. Each input or 
output flie may be stored on any medium and In any (flie 
organization supported by an I/0 moduie through lox_. The I/0 
module may be one of the Multics system I[/0 moduftes (such = as 
tape_ansI_), or one supplied by a specific installations or one 
written by a usere An Input or output flie Ls specified elther 
by a pathname or by an attach description. 


In all cases, records may be elther fixed length or variable 
length. 


KEY FIELDS 


The user can specify the key fleids to be used in ranklng 
records. Key fields are described in the Keys statement - or in 
the keys structure - of the Merge Descriptlon. Up to 29 key 
flelds may be speclfled. Any PL/I string or numeric data tyne - 
except comolex or pictured - may be speclfied for a given key 
fields. Ranking may be ascending, descending, or mixed. For a 
Character string key fleid, the collating sequence is that of fhe 
Multics standard character sete The records of each input file 
must be In order according to those key fleids. 


Aiternatively, the user can suppiy a compare procedure, 
which is then used to rank records. The ~ecords of each Input 


flie must be In order according to the atgorithm of that 
procedure. 


The original Input order of records with equal keys Ils 
preserved (FIFO order). Original inout order is defined as 
(END) 
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foliows: 


ie If two equal records come from different Input flies, then 
the record from the fille which Is specifled eartier in the 
jist of input flles (Cin the input specs subroutine argument) 
is firste 


2s If two equal records come from the same Input files then the 
record which is eartier in the fille ls first. 


EXITS 


The Merge provides exits to user suppiled procedures at 
specific points during tne merging process. Exit procedures are 
named in the Exlts statement - or in the exits structure - of the 
Merge Description. fhe following exlt points are provided? 


output_record To perform special processing for each output 
record, such as deleting, inserting, or 
aitering records to be output from the Merge3 
or summarizing data by accumulating It Into a 
summary record. 


compare To compare two records; that iss to rank them 
. for the merging process. 


Detaits of exit procedures are given below under the heading 
Writing Exit Procedures. 


(END) 
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Usage’ 


dcl merge_ entry 
call merge_ 


where’ 


1s input _specs 


-Input_fille path 
elf pathname 


-input_descripti 
“-ids attach_desc 


2e outputf_spec 


((¥)chnar(*), char (*), (*) ptr, 
char(*), fixed bin(35))$ 


(Input specs, outout_spec, merge _desc, 
user_out_Sw, code) $ 


is an array containing the specifications of 
the Input flles. Up to 10 input files may be 
specified. The array extent specifles the 
number of Input files. (Input) — 


Input flle } ls speclfied in the array 
element input _specs(j). in one of the 
following forms: 


name . 
If an input file is In the Multics 
storage system and its file organization 
is either sequential or indexed, then if 
may be specified by Its pathname. The 
fite may be elther a single segment or a 
multisegment file. The star convention 
can not be used. 4 


An Input fite snonecifled by a pathname 
wiil pe attached using the attach 
description “vflie_ pathname”. 


on attach desc 

If an input file is not In the Muttics 
storage system or its fiie organlzation 
is neither sequential nor indexed, then 
it must be specified by an attach 
description. The target I/o module 
specified via the attach description 
must support the sequential_inpuft 
opening mode and the lox, entry point 
read _recorde 


Pathnames and attacn descriptions can be 
intermixed In the input specs array. 


Is the specification of the output flie. 
Only one output file may be specified. 
(END) 
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(Input) 


The output file may be specified In one of 
the following forms’ 


-outputf_flle pathname 


-of pafnname 


-output_descript 
-oaqs attach_desc 


merge_desc 


user_out_sw 


If the output flie is in the Multics 
storage system and its file organization 
is sequential, then It may be svecifled 
by Its pathname. The file may be either 
a single segment or a mufltisegment file. 


The equals convention can be used. If 
it is, it Ils appiied to the pathname of 
the first Input Fite and the first Input 
file must be specifled by a pathname, 
not by an attach description. 


An output fille specifled by a pathname 
wlll be attached using the attach 
descriptior “vfille_ pathname™. Thus if 
the flie does not exist, It wll! be 
createde If it does exist, it wlll oe 
overwritten. 


lon attach_desc 

If the output file is not In the Multics 
storage system or Its flte organization 
Is not sequentlal, then it must be 
specified by an attach description. The 
target I/0 modute specified vis the 
attach description must supoort the 
sequentilai_output opening mode and the 
lox, entry point write_record.e 


ls an array of pointers to the Merge 


Jescriptione See the heading Merge 
Description below. (Input) 


specifies tne destination of both the summary 
report and diagnostic messages for errors 
dJetected in the arguments to merge_ or In the 
Merge Description. (Input) 


This argument may have the following values? 


(END) 
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5. code 


NOTES 


oe = write the summary revort and 
diagnostic messages via the I[/0 
SwHlftch user_outpuf. 


do not write the summary report 
and diagnostic messages. If any 
errors are diagnosed, merge_ 
wlif return with the status code 
bad_arg out information about 
the numoer and nature of the 
errors ls not avalltlable. 


*oab c= 


wrife the summary report = and 
diagnostic messages via the I/0 
switch named switchname. The 
Switch musf be attacnea and open 
for stream output. 


Mi 


sxiltcnname 


is a standard Multics status code returned by 


merge_.« Possible vatues are listed below 


under the heading Status Codes. (Outout) 


Any pathname may be relative (to the user*s current working 
directory) or absolute. 


STATUS CODES 


The following 


Status codes may be returned by merge_ (all 


codes are in error_tabtie_) 3 


8 


bad_arg 


fatal_error 


Normal return (no errors). 


One or more arguments specified to merge_» 
inctuding tnose In the Merge Descriptior, was 
Invalid or inconsistent. The Merge will have 
previously written diagnostic messages as 
directed by tne user_out_sw argument. The 
merging process itself nas not been started. 


The Merge has encountered ae fatal error 
during the merging processe The Merge wlll 
have previously generated a specific error 
message and signalled the Sub_error__ 
condition via the sub_Lerr_ subroutine. 


(END) 
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out_of_sequence 


The call to merce. is not In the sequence 
required by the Merge$3 that Is» merge_ has 
been called after initiation of the Merce buf 
pefore termination of that Invocation. 


(END) 
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Merge Description 


The Merge Description contains additionai information to 
specialize the Merge for a particular execution. The Merge 
Description is specified via the merge_desc argument to merge_.e 
The information specified may be? 


Keys - Description of one or more key fleids used (for 
ranking records. 


Exits - Specification of which exit points are to be used 
and the names of the corresponding user supplied 
exit procedures. 


A Merge Description is requlrede As a minimums the user 
must specify how records are to be ranked, either by describing 
key fleids in the Keys statement or by naming a compare exit 
procdure in the Exits statement. Other information In tne Merge 
Descriptlon Is optional. 


The Merge Description may be suppiied to merge_ in elther of 
two forms, called source form and internal form. 


The source form of the Merge Deserlption is written exactly 
as specified for the merge command {see the Multics Programmers‘ 
Manual, Commands and Active Functions, Section III), and 15 
Stored as an ASCII segment; that iss as an unstructured filie In 
the Multics storage system. If source form is used, then the 
merge _ desc argument to merge_ must have an array extent of 1 and 
the one polnter must be a pointer to the segment. (The segment 
must contain onty the Merge Description.) The source form Is 
useful when the user writes the Merce Description and supolies It 
to the procedure which calis merge_. 


The Internal form of tne Merge Description Is a set of one 
or two structures. The merge_desc argument must have an array 
extent of 2+ and the two pointers are pointers to the _ two 
structures. Any of the structures can be omitted; in that case 
the corresponding pointer must be null. Tne pointers must be 
specifled in the array in the foitoxwlng order? 


addr (keys) 
addr (exits) 


where the two structures (keys and exits) ate defined below. The 


internal form is useful when the procedure céelilng merge_ 
constructs the Merge Description. 


(END) 


Page 75 


merge_ merge 


a i Ee cis eee elaine cas Se aD ee coma 


KEYS STRUCTURE 


The keys structure is used when the catiter describes key 
fieldse Tne Merge*s standard compare routine wlll then be used 
to rank records. If the catter describes keys, then the compare 
exit must not be specified. 


If tne calier does not describe keys, then the corresponding 
pointer in the array merge _desc must be nul fi and the compare exit 
must be speclfled In the exits structure. The user suppliled 
compare routine will then ve used fo rank records. 

Tne keys structure Is? 


dc! i KeySe 


2 version fixed bin init (1), 
2 number flxed bin, 
2 key_desc(user_keys_number refer (keys. number)), 
3 datatype char(8), 
3 slze fixed bin(24), 
3 word_offset fixed bin(18), 
3 bit offset fixed bin(6), 
3 desc char (3) 3 
where’ 
1. version is the version number of the structure (must 
be 4). 
2e number ls the number of key fields, estabilshed by 
the value of user_keys_number. 
3e key_desc is an array of key descriptions. Each key 
description is one element of the array. The 
key descriptions must be specifled In order, 
the major key first and the most minor key 
laste 
%&. datatype Is the data type of the key fleld. See the 
table betow for the encoding of datatype. 
The value must be teft justifled within 
datatype. 
5. 6size is the size of the key fleld, in units which 


depend on the data type. 


For string data types, size is the exact 
fength (characters or bits) of the fleld. 


(END) 
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if 


8. 


word_offset 


bit_offset 


desc 


For arithmetic data types:s sIze is the 
precision (binary or decimal diglts) of the 
fleid. The space occupled is determined by 
precision in combination with the data type. 
The space occupled is not adjusted for an 
aligned field. For example, for an aligned 
fixed binary fieid of one word, size must be 
specified as 353 for an aligned floating 
binary fleid of two words, size must be 
specified as 63. See the tablte below for tne 
semantics of size. 


ls the word portion of the offset of =the 
beginning of the key fields relative to the 
beginning of the record. Consider the record 
as being aligned on a word boundary, as will 
be the case for a Multics PL/I structure. 
Words are numbered from 9 for the first word 
of the record. 


is the bit portion of the offset of the key 
fleid; that is, the obit offset within the 
word in which the key field begins. S8lts are 
numbered from 0 to 35. (If the fieid is 
aligned on a word boundary, then blt_offset 
ts ge) 


indicates whether ranking for this key field 
is to be ascending or descending. PossIlbie 
values are 


use ascending rankings 


il 


“dsc™ = use descending ranking. 


(END) 
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DATATYPE ENCOOING ANO SEMANTICS OF SIZE 


Encoding 1! Semantics of slze 


of } (where slze = n) 
datatype ! Unit Range Space Occupled 
Cnaracter string char 9 bit 1 - 4095 on characters 
(Multics ASCII) character . 
Bit string pit 1 bit 1 - 4995 on obits 
Fixed binary din 1 bit 1-*+ 71 n+14 oblts 
Floating binary fibin 4 bit 1 - 63 n+9 olts 
Fixed decimal dec 9 bit 1 - 59 n+ 1 digits 
(leading sign) digit 
Floating decimal fioec 9 obit i - 59 n+ 2 digits 
digit 
(END) 
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The exits structure i[s3 


dcl 1 exits, 


1 version flxed bin init(1), 

2 compare entry, 

2 reserved entry init (mer ge_Snoexit), 
2 output record entry; 

where? 

1. version is tne version number of the structure (must 
be i). 

220 compare specifies tne entry point of a user sunopltlied 
compare exit procedureée If the caller 
describes key fleids (supplies a keys 
structure), then this exit must not be 
specified. 

3. reserved is reserved for future usee 


4%. output record specifies the ertry point of a user supoliled 
output _record exif procedure. 


ENTRY VARIABLES 


In the exits structure, each exit point Is specified via an 
entry variable. The entry variable musf be set (elther 
initialized or assigned) by a user procedure, normally the 
procedure which calis merge_. The entry variable can. identify 
eitner an Internal entry point (that Is, an Internal procedure) 
or an external entry polnt of the procedure which sets the entry 
variable; or it can identify an external entry point of another 
user procedures 


If none of the exits deciared in the exits structure is to 
be used, then that structure can be omitted and the 
corresponding pointer in the array merge_desc must be null. If 
the structure is inciuded but an exit specified in it is not to 
be used, then the corresponding entry varlable must be sef to 
merge_$noexlt, which is deciared? 


dc! merge_tnoexit antry external $ 


(END) 
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An exit polnt may not be aitered after the cail to merge_. 
Any change to the entry varlable thereafter wlli have no effect. 
However, certain entry polnts can be dlsableds as specified In 
tne aescriptions of the individual exit procedures below. 


(END) 
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Weiting Exit Procedures 


A user supplied exit procedure is called by the Merce to 
perform a specifled function. The user procedure must perform 
that function, and tnen must return to the Mergee The user exit 
procedure may perform additional functions desired by the user. 


Certain exit procedures reptface tne corresponding standard 
routine of the Merge. Other exlt procedures supplement the 
normai functions of the Merge. Tnis is specified for each 
Individual exit procadure below, 

The following exit points are provided? 


output record 
-compare 


Ali exit polnts may be active during the same Invocation of 
the Merge. 


The entry point names of ali user supptled exit procedures 


are defined by the user. Specific names are shown below cniy for 
convenlence in discussion. 


(END) 
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COMPARE EXIT PROCEDURE 


A compare exit procedure replaces the standard record 
comparlson procedure of the Merge. The Marge calls the comprare 
exit procedure each time the merging process is ready to rank two 
records;s that Is, to determine which of the two is first In the 
merged order. 


A compare exit procedure must perform tre following 
function’ The compare exit procedure secelves as arguments a 
pointer to each of tne two records. The compare exit procedure 
must determine which of the two records is first - or that they 
are equal in rank - and must return a corresnoonding return vatue 
to the Merge. The compare exit procedure is Invoked as a 
functione 


Usage 


comparet oprocf{rec_ptr_is rec _ptr_2) returns(flxed bin(1))3 


deci (rec_pfr_i ptr, 
rec_ptr_2 ptr) parameter 5 
dci resuit flxed bini1)3 


return(result)5 
end compare; 


where: 

de rec_ptr_i Is a pointer to a doudie word aligned buffer 
containing the first record of the pair to be 
comoared. This record Is always the first of 
the two accordirg to the original Input 
ordere (Input) 

2e reciptr_2 ls a polnter to a double word allgned obuffer 
containig the second record cf the palr to be 
compareds (Input) 

3e result is the result of tne comparisone (Output) 


Possible vaiues are? 


0 = the two records rank equal. 


(END) 
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the record polnted to by rec_ptr_i ranks 


-i1 = 
first. 
+1 = the record pointed to By rec_otr_2 ranks 


first. 


If a compare exit proceaure requires the ftength of elther 
record, it is available in the word preceding that record in the 
forms: 


dci rec_ten fixed binl2il) aligned; 


A compare exit procedure cannot alter either the content or 
the length of either record. 


(END) 
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OUTPUT_RECORD EXIT PROCEOQURE 


An output _record exit procedure supplements the standard 
output writing function of the Merge. The Merge calls the 
output_record exlt procedure? 


1e Each time it nas dcetermined the next record in ranked order 
from the merging process} 


Ze Once more after the last record has been obtained from the 
merging process (end of oufput)}3 


30 Additionally, each time the output record exlt procedure 
returns with an action of insert. 


Tne Merge gives the output record exit procedure access to 
two records? | 


4. the output record, about to be written to the outout file. 
2e Tne next record, the record fteaving tne merging process. 


An output _record exlt procedure need not perform any 
processinge If it does nots then the output record is accepted 
for the output flie. 


An outout_record exit procedure may perform the following 
functions, which are accomplished via the values of arguments 
returned when the oufput_record exit procedure returns to the 
Merge’ 


Accept the output record. This Is accompiisned by setting 
actlon = 0. 


Delete the output recorde This is accomplished by setting 
actlon = 4e 


Delete the erecora leaving the merge. This is accomollshed 
by setting action = 2e 


Insert one or more records after the output record. (At the 
first call to the output record exit procedure, records may 
be inserted at the beginning of output. At the ltast call to 
the output _record exit procedure, records may be inserted at 
tne end of output.) This is accomplished by setting 
rec_ptr_2 to polnt to the record to be Inserted, setting 
rec_ften_2 approorlately, and setting action = 3. 


(END) 
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each 


Usage 


Alter the output record, oefore It is written to the output 
file. This is accompiished by altering the record opolnted 
to by reclptr_i or setting rec_ptr_1 to polnt to another 
record, setting rec_!en_1 appropriately, and setting action 
= 0 to accept for action = 3 to Insert). 


Summarize data Into the first record of a sequence of 
records with equal keys, and delete the succeeding records 
of the sequence. This may be accomplished as follows: At 
the first call to the output _record exit procedure, set 
equal key checking on (equal_key_sw = “4™"). At subsequent 
calis to the output record exit orocedure, If the output 
record and the record teaving the merge have equal keys 
(equal_key = 9), then accumulate data Into the output record 
and delete the record lteavig the merge (actlon = 2). If the 
two records nave unequal keys (equal_key # 0), then accept 
the output record (action = 9). 


Summarize data into the last record of a sequence with equal 
KeySs and deiete the preceding records of the sequence. 
This may be accomplished as follows: At the first call to 
The outfput_record exit procedure, set equal key checking one 
At subsequent calls, if the two records have equal keys then 
accumulate data into a work area and delete the output 
record (actlon = 1). If the two records have unequal keys, 
then aiter the output record using the accumulated data and 
accept that record (taction = 0). 


Sequence check the oufput file. This is accomplilshed by 
setting seq _check_sw = “i". If the output record will not 
collate properly with the output filles or does not have Its 
keys In the position specifled to the Merge, then set 
seqa_check_sw = “Q". 


Ciose The exit point so that the output_record exit 
procedure wilt not be calied agaln during this execution of 
the Merge. Tnis is accompilshed by setting close_exift_sw = 


i Hed 


The outpuf_recora exit procedure must return to the Merge 
time it Is cal ted. 


output_record: proctrec_ptr_is rec_len_is rec uptri2, rec_len_2> 


actlon, equal_key, equal_key_sw, 
seq_check_swe close_exif sw); 


(END) 
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dcl (rec uptrii 
rec_lten 1 
rec_ptr_2 
rec_len_2 
action 
equal_key 


merge. 


ptr, 

fixed bin(2i), 
Oth», 

fixed bin(2i), 
fixed bln, 
fixed bln(1), 


equal_key_sw pitti), 


seq_check_ 


3 biti), 


close_exit_sw obit(i) ) parameters; 


where’ 


1. 


ce 


Se 


rec_optri1 


rec_len_i 


rec_otr_2 


points to a doubie word aligned buffer 
containing the Output recorde The 
output record exit procedure may atter the 
contents of this record or may change the 
pointer to point to another record. The 
Merge uses the vatue of rec_ptr_1 returned to 
it by the output record exlt procedure as 
specified below in fhe description of the 
action argument. (Input/Output) 


At the first call to the output_record exit 
procedure (beginning of outout), fThere is no 
output record and rec_otr_i = null). 


is tne tength of the output record in bytes. 
The output _record exit procedure may change 
the length of tris record. The merge uses 
the value of rec_len_i returned to It by the 
output_record exit procedure as specified 
below in the descriotion of the action 
argument. (Input/Outout) 


points to a doubie word atlgnea buffer 
containing the record fteaving the merge. The 
output record exit orocedure may not alter 
the contents of this record. For all actlons 
except Insert, the Merge will Ignore’ the 
vaiue of rec_ptr_2 returned to It by the 
output _record exit procedure. If the actlon 
is insert, then the output_record exlt 
procedure must change rec_ptr_2 fo point to 
the record to be Inserted. (Input/Output) 


At the fast call to the output_record exit 
procedure (end of output), there is no record 
leaving the merce and rec ptr_2 = null (). 


(END) 
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rec _len_2 


action 


merge 


is the length of the record leaving the 
merge. The output_record exlt procedure may 
not change the length of this record. For 
al! actions except insert, the Merge wlll 
ignore the value of rec_ien_2 returned to It 
by the output record exit procedure. If tne 
action is Insert, then the output_record exit 
orocedure must set rec_len_2 to the lencth of 
the record to be inserted. (Input/Output) 


Indicates the action to be taken upon return 
to the Merge. (Input/Output) 


Possible values of action are? 


0 = accept the output recorde . The output 
record is written to the output file. 
The Merge uses the returned values of 
rec _ptr_i and rec_len_i to identify the > 
record to be writtene At the next cai! 
to the oufput_record exit procedure, the 
record teaving the merge becomes the new 
output record, and anew record teaving 
The merge has been obtained. 


Each time the output_record exit 
procedure is called, tne Merge sets 
actlon to this value. 


14 = delete the output record. No record is 
written to tha output file. The Merge 
Ignores the returned values of frec_otr_1 
and rec_tfen_ie At the next call to the 
output_record exit procedure, the record 
leaving the merge becomes the new oufput 
record, and a new record tleaving the 
marge has been obtained. 


2 = delete the record teaving the merge. 
{This action should be used for 
summarization into the output record.) 
No record is written to the output file. 
At the next cail to the output_record 
exit procedure, fhe output record remains 
the same, and a new record teaving the 
merge has been obtained. The Merge uses 
the returned values of erec_oetr_i and 
rec_lten_i to identify the output record 


(END) 
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equal_kKey 


merge_ 


for that next call to the output record 
exit procedure. 


3 = Insert a record after the output record. 


Tne output record is written to the 
outout fillie. The Merge uses the returned 
vaiues of rec_popftr_i and erec_len_i_ to 
Ildentify the record to be written. The 
Merge calls the output_record exit 
procedure égaln, so that the inserted 
record may be accepted or an additional 
record may be Inserted. At this next 
call to the output_record exit procedure, 
the Inserted record becomes” the new 
output record, and tne record leaving the 
merge remains the same. The Merge uses 
the returned values of rec _pt_2 and 
rec_len_2 to ldentify the inserted 
recorde 


At tne tast cail to the output lrecord exit 
procedure {end of output)> If the 
output_record exit procedure inserts records 
then they are appended at the end of output. 
Any other vailue for action means do not 
append any records, and the output record 
exlt will not be taken agaln. 


Indicates whether the output record and the 
record feaving the merge have equal keys. 
(Input) 


Possible values are? 
0 = the two records rank equal. 


the two records do not rank equal. At 
the first and fast calis to the 
output_record exit procedure, (beginning 
of outout and end of output), only one 
record is present and the Merge sets 
equal_key to this vaiue. 


+1 


If the user suppiled key descriptions, then 
the value of equali_key is determined only by 
those key flelds; the orlgina!l Input order 
9f the two records is not used to resolve key 
equality. If the user supptied a compare 


{ENO) 
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7e equal_key_sw 
8. seq_check_sw 


merge_ 


exit procedure, then the Merge uses the 
resuit of that compare exit procedure to set 
the vatue of equal_keye. (In elther case, If 
the two records rank equal then rec_Lotr_i 
points fo fhe record which is first according 
to the original Inout order of the two 
records.) 


indicates whether or not equal key checking 
is to be performed. (Input/Output) 


Posslble values are’ 


"9" = do not check for equal keyse At the 
first cali to the output_record exit 
procedure (beginning of output), fhe 
Merge sets equal _key_sw to this value. 


“4% = check for equal keys before the next 
call to the output_record exit 
procedure. 


Since equal key checking takes times the user 
Should set equal_key_s# = "4" onty when 
required for actlons such as summarization. 


indicates whether or not sequence checking is 
To be performed. (Input/Output) 


Possible vaiues are? 
"9g" = do not sequence check. 


"4" = sequence check. At the first call to 
the output_record exit procedure 
(beglnning of outout), the Merge sets 
seq_check_sw to this value. 


Sequence checking means comparing the output 
record to the record previously written to 
the output file. Sequence checkirg is 
performed after the output_record exit 
procedure returns to the Merge, and only if a 
record Is to be written to the oufput file 
{that is, only if the action is accept oor 


insert). If the user suppiled key 

descriptlons, then the Merge*s key comparison 

routine is used. If the user supoliea a 
(END) 
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close_exif_swa 


compare exit procedure, then that exit 
procedure is called. 


If the output record is out of sequence with 
the previous record, then the status code 
fatai_error 1s returned to the caller of 
merge_$; see the entry merge_ above. 


A¢' records written to the output file, 
including Inserted records, can be sequence 
checked. 


indicates whether the exit is to be closed 
hereafter. (Input/Output ) 


Possible values are? 


"9" = keep this exit open. Each time the 
output _record exit procedure is called, 
the Merge sets ciose_exit_sw to this 
value. 


“4™ = close this exIlt. The Merge will not 
call the output record exit procedure 


again during tnis executlon of the 
Merge (even If the action is insert). 


(END) 
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RECORD POINTERS 


Since the Merge aligns each record In a buffer on a double 
word boundary, if an exit procedure apoiies a based deciaration 
of the record to the opointer(s) then correct atignment Is 
ensureds 


ORIGINAL INPUT ORDER (FIFO) 


For the compare and output_record exlt procedures, rec_potr_i 
always polnts fo the record whose original. input order was prior 
to the record pointed to by rec _potr_2- If a compare ex{t 
procedure returns with an equal ranking for the two records, then 
this original input order is preserved. dIrigina!l Input order has 
been defined earller under the neading Key Fleids. 


Name? sort 


The sort command is described In the Multtics Programmers’® 
Manual, Commands and Active Functions, Section III. This 
description incitudes only additional optional control! arguments 
which are not described in MPM Commands. 


Ysage 


sort inout_specs outputf_specs control _args 


where’ 
32 controt_args can be chosen from the following (in aadition 
to those control arguments specifled in MPM 
Commands) 
-time prints timing information for the Sort? 


System toad {hnmu) 
Merge order 
String size 
and for each phase of fhe Sort’ 
Elapsed time 
Real cou fime 
Virtual cpu time 
Page faults 
Paging device faulifs 
Comparisons executed 


(Times are glven In seconds.) 


(ENO) 
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“-merge_order 


-string_slze s 


-debug 


Sort/Merce PLM 


specifies that the merge order is to be 
Me The argument m must be a decimal 
Integer. This argument is meaningful 
oniy if alt input files are in the 
Storage System, so that the fotal input 
flie size can be obdtained by fhe Sort. 


specifies that the string size (as 
produced during the presort) Is to be § 
bytes. The argument § must be a decimal 
integer, and must be fess than the 
system maximum segment size.e The actual 
slze of any string may differ somewhat 
from Ss, since the tength of the tast 
record Inserted into the string may not 
exactly match the soace avallable. 


Merge order and string slze cannot poth be 
specified. 


speclfies that temporary files wlll be left 
Initiated (but truncated to zero tength) 
after compietior of the Sorte This argument 
is intended for use with performance 
measurement and analysis tools which print 
reference names, such as sample_refse 


If this argument Ls omitted, temporary files 
will be deleted after completlon of the Sort. 


If -debug is specifled, deletion of temporary 
flies must be done explicitly oy the user. 
Some temporary filles are in the process 


directory; tne work files are In the 
directory specified by the -temo_dir 
argumente The names of all temporary flies 


are generated uniquely for each Invocation of 
the Sorts and always contain the string 
“eon ts 


(ENO) 
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Name? merge 


The merge command Is described in the Multics Programmers’ 
Manual, Commands ana Active Functions, Section III. This 
description inciudes only additiorat optional contro! arguments 
which are not described in MPM Commands. 


Usage 


merge inouf_specs output specs control_args 
wheres’ 


32 control_args can be chosen from the following (Ln ‘addition 
to those control arguments specifled In MPM 
Commands)! 


-time prints timing information for the Merge? 
System load (nmu) 
and for each phase of the Merge: 
Elapsed time 
Real cpu fime 
Virtual cou time 
Page faults 
Paging device faults 
Comparisons executed 


{Times are given in seconds.) 


“debug specifies that temporary files wlll ba 
feft initiated (but truncated to zero 
length) after completion of the Merge. 
This argument Is Intended for use with 
performance measurement and analysis 
tools which orint reference names, such 
as sample_refs.e 


If tnis argument is omitted, temrorary 
flies wllt be deleted after comcletion 
of the Merce. 


If -edebug Is speclifled, deletion of 
temporary files must be done explicitly 
by the usere Alt temporary files are in 
the process directory. The names of ati 
temporary fltes are generated uniquely 
for each Invocation of the Merge, and 
always contain the string “sort_™ 
(END) 
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Name sort_ 


The sort. subroutine is descrloed in the Multics 
Programmers* Manual, Subdroutines, Sectlon IIe This descriotlon 
includes only additional! entry polnts which are not described in 
MPM SubroutInese 


Entry: sort_$%inltiate 
The sort ltinitiate entry point Is used when the Sort Is 

“driven™ by Its calfar.e. The Sort is sald to be driven if the 
caller suppiies a procedure which calls for directiy performs) 
the input flle processing and outonut file processing procedures. 
Such a driver must have fhne following general form: 

call sort_sinitiate lar guments) 3 

cali inout_file_proc (code) 3 

call sort_tcommence (code) 3 


call ouftput_file_proc(code) 5 


call sort_sterminate (code) } 


where: 

1. sort_$initlate is the procedure of the Sort which must 
be called first (it “Initlates" the 
Sort). 

2e Input_flle proc Is an Input_file procedure, as specifled 
in the description of the sort. 
subroutine in MPM Subroutines. Instead 
of calling an Inout_file procedure, the 
driver may perform the necessary 
functions directly. 

3-2 sort _$commence is the orocedure of the Sort which = must 
be calfted when the Input _fllie procedure 
has completed releasing records to the 
sorting process (lt “commences™ the 
merging process). See the entry 
sort _tcommence bel owe 

4 outout_fite_proc Is an output_file procedure, as 


specified in the description of the 
sort. subroutine In MPM Subroutines. 
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Instead of calling an oufput_file 
procedure, the driver may oerform the 
necessary functions directly. 


5s sort _$terminate ls the procedure of the Sort which must 
be called when the output_fille procedure 
hes completed retrieving recoras from 
the Sort (it “terminates™ the sorting 
process). See the entry sort_$terminate 
 vbelow. 


The entry polnts sort _8initiates, sort _tcommence, and 
sort_$terminate are specifically designed to be used by COBOL 
object programse They support the ANSI COBOL Sort/Merge Module, 
Level 2 (the SORT, RELEASE, and RETURN statements). 


Normally, when calted as a command (sort) or as a subroutine 
(sort_)» the Sort itself contains the driver to perform the five 
calis listed above. 


Usage 


del sort_tinitiate entry({char(*), otr, ptr, 
char (*), float bin(27), fixed bin(35))$ 


call sort_$initlate(temp_dir, keys_ptrs exits_otrs 
user_out_Sw, file _slze,s code)3 


wheres’ 


i. temp_dir is tne pathname of tne directory which wilt 
contain the Sort*s work files. If this 
argument is ““, then work files will be 

contained In the user*s process directory. 


This argument should be used when the process 
directory wilf rot be farge enough to contain 
the work flles. The get_dir_ functior may be 
used to obtain the name of the user’s current 
working directory. (Input) 


2e keys_ptr ls a polnter to the keys structure, which 
describes the key fleids to be used for 
ranking recordse This structure is idertica! 
to that specified under the heading Keys 
Structure in the description of the sort_ 
subroutine in MPM Subroutines, Section II. 
If the user 1s supplying a compare exit 
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procedure, then keys_ptr must be null and the 
compare procedure must be specifled in the 
axits structure. (Input) 


is a polnter to the exits structure, which 
speclfles which exit points are to be used 
and gives the entry point names of the 
corresponding user suppiled exit procedures. 
This structure is identical to that specified 
under the heading Exits Structure In the 
description of the sort. subroutine In MPM 
Subroutines, Section II. If no exits are _ to 
be used, then exlits_ptr must be null. If the 
compare exIlt is specifled, then keys must not 
be described. (Input) 


specifies the destination of both the Sort’s 
summary report and dlagnostic messages for 
errors detected in the arguments to 
sort_sinitlate. (Input) 


This argument may have the following vatues? 
ee = write the summary report and 


diagnostic messages via the I/0 
Switch user_outpuf. 


"eb f™ = do not write the summary report 
and diagnostic messagesSe If any 
errors are dlagnosed, 


sort_$S$initilate wllf return wlth 
the status code bad_arg but 
Informatlon about the number and 
nature of the errors Is not 
aval labile. 


write the summary report = and 
dlagnostic messages via the I/0 
switch named switchname. This 
switch must be attached and open 
for stream outpute 


sniltchname 


is tne total amount of data to be sorted, in 
miltions of bytese If this argument Is zero, 
the default assumption is approximately one 
mliijlon bytes (fite_size = 1.0). (Input) 


The file size argument is used for 
optimization of performance 3 the actual 
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amount of data can be considerably targer 
“aitnout preventing the Sort from completing. 
Tne maximum amount of data which can be 
sorted is (in bytes) approximately 69 milllon 
times the square root of file _size. 


62 code is a standard Multics status code returned by 
sort_$initiate. Possible values are ItIsted 
beiow under the heading Status Codes. 
(Output) 


Entry Variables 


Entry variables In the exits structure should be set 
(elther initialized or assigned) by the procedure which callts the 
sort_Iinitlate entry polnf. 


Cleanuo Handling 


In order that the Sort can be terminated prooerly in case of 
an abdnormal exit, the cleanup procedure of the caller of 
sort_8initiate must Include a calf’ to the entry point 
sort_S$terminate. 


gtatus codes 


Tne following status codes may be returned by sort_$initlate 
(all codes are In error_tabie_) 


0 Normal return (no errors). 


bad_arg One or more arguments specified to 
sort_Sinitilate, including the keys and exits 
structures, was invalid or inconsistent. The 
Sort wlli have previously written dlagnostic 
messages as directed by the user_out sw 
argumente The sorting process itself has not 
been started. 


fatal_error The Sort has encountered a fatal error. The 
Sort will have previously generateda a 
specific error message and signalied the 
sub_error_ condition vila the sub_err _ 
subroutine. | 
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Tne call to sort_$initiate is not in the 


sequence required dy the Sort; Coes 
sort_sinitiate has been called after 
initlation of the Sort but before normal 
termination of that Invocation vla a call to 


sort_ttermlinate. 
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Entry: sort_scommence 


The sort _$commence entry point must be calted after the 
driver of the Sort has completed Its Input file procedure. See 
the entry point sort_Sinitilate above. The cail to sort_Scommence 
informs the Sort that end of input nas been reached. Upon return 
from sort_Scommence, tne driver can begin its outputflle 
proceduree 


Usage 
dcl sort_tcommence’ entry(fixed bin(35))5 
call sort _$commence(code) $ 


where code is a standard Muitics status code returned by 
sort _Scommencee Possibie values are tisted below under fhe 
heading Status Codes. (Output) 


Status Codes 


The following status codes may be returned by sort_$commence 
{ail codes are in error_table_)3? | 


9 . Normal return (no errors). 


fatat_lerror The Sort has encountered a fatal error during 
the sorting processes The Sort will have 
previously generated a specific error message 
and signatted tre sub_error_ condition via 
the sub_err_ subroutine. ; 


out_of_sequence The catt to sort _$commence is not in the 
sequence required Dy the Sorts CeJes 
sort_s$commence has been called before 
sort _8initiate. 
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Eniry: sort_$terminate 

The sort_éterminate entry polnt must be called after the 
driver of the Sort has compieted its output_file orocedure. See 
the entry point sort_$Sinitiate adDove.s The call to 
sort_$terminate informs the Sort that the current executlon of 


the Sort is complete, Upon return from sort_$terminate, the 
caller can Initiate another execution of the Sorte 


Usage 
dci sort _$terminate entry(fixed bin(35)) 3 
call sort_Sterminate(code) 3 
where code is a standard Multtics system status code returned by 


sort_$terminate. Possible vatues are tisted below under the 
heading Status Codes. (Output) 


alatus Codes 


The fottowlng status codes may be returned by 
sort_$terminate (ati codes are in error_tabdle_)3 


H] Normal return (no errors). 
out_of_sequence The call to sort_$terminate is not In the 
sequence required by the Sort; Cede 


sort _Sterminate has been calied before 
sort_tinitiate. 


(END) 
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